DEV Community: Edouard Maleix

Securing MCP Servers with OAuth2: Ory Hydra + Claude Code + ChatGPT

Edouard Maleix — Fri, 30 Jan 2026 15:18:26 +0000

A client asked me to secure their MCP server. Simple enough — throw in some API keys, right?

But the Model Context Protocol spec had other ideas: OAuth2 with Dynamic Client Registration, Resource Indicators (RFC 8707), Protected Resource Metadata (RFC 9728)...

One week and dozens of authentication bugs later, I have an MCP server that works with Claude and ChatGPT. Here's everything I learned — so you don't have to repeat the dance.

Why Not Just Use API Keys?

You're building an MCP server — an API that lets AI assistants like Claude and ChatGPT call external tools. Your first instinct: add a simple Authorization: Bearer sk-... header and call it a day.

Then you read the MCP Authorization spec (2025-11-25 revision) and realize¹:

OAuth 2.1 (draft-ietf-oauth-v2-1) is MUST
Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document) is SHOULD
Dynamic Client Registration (RFC 7591) is MAY
Resource Indicators (RFC 8707) is MUST
Protected Resource Metadata (RFC 9728) is MUST
Authorization Server Metadata (RFC 8414) is MUST

"This is overkill for my side project," you think.

But here's the reality: major MCP clients already implement these specs — Claude, ChatGPT, LibreChat, and others. Your MCP server either speaks OAuth2 correctly, or it doesn't work with any of them.

Why OAuth2 Matters for MCP Servers

If you're new to OAuth2: think of it as a crowd of services dancing together — one misstep and the whole routine falls apart.

You, when you implement OAuth2 for the first time

In our setup, the crowd includes:

Your MCP Server (the API you're protecting)
Ory Network (the bouncer checking credentials)
GitHub (proving who you are via social login)
MCP clients like Claude, ChatGPT, or LibreChat (requesting access)

Each dancer has a role, and OAuth2 is the choreography that makes them work together without your MCP server ever seeing passwords.

Why go through this trouble instead of simple API keys? OAuth2 solves real security problems:

User Context

MCP servers need to know who is making requests. Without proper auth:

All users share the same data (no privacy)
No audit trail (who did what?)
Can't implement rate limiting per user
Resource ownership is impossible

Token Lifecycle

OAuth2 access tokens expire by design. API keys can have expiration dates too, but in practice most don't — and even when they do, rotation is manual and easy to forget. OAuth2 bakes this in:

Short-lived access tokens limit the blast radius of a compromise
Refresh tokens enable seamless rotation without user disruption
Revocation is immediate (especially with opaque tokens + introspection)

Scope Limitation

OAuth2 tokens carry scopes (permissions):

openid = identity information
offline_access = refresh tokens
Custom scopes = fine-grained access control

A single API key is all-or-nothing. OAuth2 tokens can be scoped to specific operations.

Standard Protocol

MCP clients already implement OAuth2. If you use API keys:

You need a custom authentication flow
MCP clients won't auto-discover your server
You're maintaining non-standard auth code

Security by simplicity: Using OAuth2 means following a proven standard instead of rolling your own authentication.

Okay, I'm lying — OAuth2 is complicated.

Learning by Doing

To make sense of all this, let's build a minimal MCP server secured with OAuth2 using Ory Hydra and Kratos. By the end, you'll have:

✅ OAuth2 authorization and consent (Hydra)
✅ Social login via GitHub (Kratos)
⚠️ Works with Claude Code CLI (with caveats - see Bug #2)
✅ Works with Claude.ai Custom Connectors
✅ Works with Claude Desktop
✅ Works with ChatGPT Web App (tested - actually works better than Claude!)
❌ Codex VSCode extension (OAuth not supported for custom servers)
✅ User-scoped resource isolation (you only see your data)

The Stack: What Each Piece Does

Why this stack?

Ory Kratos and Hydra: Identity management and OAuth2 server trusted by companies like OpenAI for scale and security
Fastify MCP: Fastify plugin, forked from @platformatic/mcp with better OAuth2 support

Part 1: Setting Up Ory Network

I use Ory Network for this guide. It hosts your Hydra and Kratos instances so you don't have to manage infrastructure.
It's the same team behind Ory Hydra, Kratos, Keto, and Oathkeeper.

Yes, they have a free Developer tier.

Step 1: Create Your Ory Network Project

Register account: Visit https://console.ory.sh and sign up
Create workspace: Click "New Workspace" (organizational container for projects)
Create project: Within your workspace, click "New Project"
- Name: "MCP Server Development"
- Region: Choose closest to you
Generate API key: Go to Developers tab → API Keys → "Create API Key"
- Save the key securely (you'll need it for introspection auth)

I can feel your sarcasm: "We use an API key to avoid API keys?" Yes, but this key is for Ory Network management only, not for your MCP server clients.

Note your project details:

Workspace ID: (in workspace settings)
Project ID: (in project settings)
Project slug: {your-slug}.projects.oryapis.com

Detailed setup guide: See Deployment to Ory Network for complete walkthrough including CLI setup.

Prefer running everything locally? Skip Ory Network and use Docker Compose. Your configuration is fully portable to self-hosted Hydra/Kratos later — I tested both, and the same JSON config works on either. This is the beauty of Ory.
This compose file is from an older project but demonstrates the full Ory stack (Hydra, Kratos, PostgreSQL, Self-Service UI).

Understanding OAuth2 Client Registration for MCP

Before configuring, let's understand why MCP needs Dynamic Client Registration (DCR). (The spec looks over-engineered — until you realize it solves real problems.)

"I just want to call an API, why do I need to read so many RFCs?"

The Problem: Unknown Clients

Traditional OAuth2 assumes you know your clients upfront:

Developer manually registers app in OAuth console
Gets hardcoded client_id and client_secret
Ships these credentials in the app

But with MCP: When someone discovers your server URL, their Claude client has never heard of your server. How do they get credentials? You can't expect every user to register manually in your OAuth console — that defeats the whole "seamless AI integration" promise.

Solution 1: Dynamic Client Registration (DCR - RFC 7591)

DCR lets clients register themselves at runtime:

Client discovers MCP server
Client reads registration_endpoint from OIDC discovery
Client POSTs metadata to register: {redirect_uris, grant_types, scopes}
Server returns new client_id (and maybe client_secret)
Client proceeds with normal OAuth flow using the registered scopes

Solution 2: Client ID Metadata Documents (CIMD)

The November 2025 MCP spec introduced CIMD as the SHOULD (recommended) approach, with DCR as MAY (optional fallback).

How it works: Clients publish metadata at an HTTPS URL they control. That URL becomes the client_id.

Example metadata at https://app.example.com/oauth/client-metadata.json:

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "My MCP Client",
  "grant_types": ["authorization_code"],
  "redirect_uris": ["http://localhost:3000/callback"],
  "token_endpoint_auth_method": "none"
}

During OAuth flow:

Client sends client_id=https://app.example.com/oauth/client-metadata.json
Authorization server fetches that URL
Server validates: client_id matches URL, redirect_uri is in allowed list
Server caches metadata (respecting HTTP cache headers)

Comparison:

Aspect	DCR	CIMD
MCP Spec Status	MAY (optional)	SHOULD (recommended)
Client ID	Server-minted UUID	Client's HTTPS URL (e.g., `/client.json`)
Registration	POST to server	Self-published JSON document
Server state	Stores records in database	Fetches on-demand, caches via HTTP headers
Best for	Local agents without reliable URLs	Web/hosted clients with stable domains
Localhost support	✅ Works fine	⚠️ Risk: anyone can claim localhost URIs

For this guide: I use DCR because:

Local agents (Claude CLI, CLI tools) don't have stable HTTPS URLs to host metadata
Ory Hydra supports DCR out of the box
DCR works for both localhost and production scenarios

CIMD note: Authorization servers advertise CIMD support via client_id_metadata_document_supported: true in their metadata. Ory Hydra doesn't support this yet, but if you're building a web-based MCP client with a stable domain, CIMD is the preferred approach per the MCP spec.

Ory Configuration Reference

Here are the key configurations you need. In Ory Network, the project config is a single JSON document that merges settings from all Ory services:

services.oauth2 → Ory Hydra (OAuth2/OIDC server)
services.identity → Ory Kratos (Identity management, social login)
services.permission → Ory Keto (Authorization, not used in this guide)

There are two ways to apply these configs:

Import JSON via CLI (fastest - paste the whole merged config)
Configure via Console UI (guided, click-through for each service)

OAuth2 Configuration (Hydra)

{
  "services": {
    "oauth2": {
      "config": {
        "oauth2": {
          "pkce": {
            "enforced": false,
            "enforced_for_public_clients": true
          }
        },
        "oidc": {
          "dynamic_client_registration": {
            "default_scope": ["openid", "offline_access"],
            "enabled": true
          }
        },
        "strategies": {
          "access_token": "opaque",
          "scope": "wildcard"
        },
        "ttl": {
          "access_token": "1h0m0s",
          "refresh_token": "720h0m0s"
        },
        "webfinger": {
          "oidc_discovery": {
            "auth_url": "https://{slug}.projects.oryapis.com/oauth2/auth",
            "client_registration_url": "https://{slug}.projects.oryapis.com/oauth2/register",
            "jwks_url": "https://{slug}.projects.oryapis.com/.well-known/jwks.json",
            "token_url": "https://{slug}.projects.oryapis.com/oauth2/token",
            "userinfo_url": "https://{slug}.projects.oryapis.com/userinfo"
          }
        }
      }
    }
  }
}

Key settings explained:

access_token: "opaque" - Use opaque tokens (revocable, secure)
dynamic_client_registration.enabled: true - Enables DCR for MCP clients
pkce.enforced_for_public_clients: true - Enforces PKCE for CLI clients like Claude Code
webfinger.oidc_discovery.client_registration_url - Can override for DCR proxy (see Bug #1 workaround)

Why opaque tokens?

Immediate revocation (logout, compromised tokens)

No JWT parsing vulnerabilities

Token contents stay server-side

Ory's introspection is fast and cached

Identity Configuration (Kratos - for GitHub login)

{
  "services": {
    "identity": {
      "config": {
        "selfservice": {
          "methods": {
            "oidc": {
              "config": {
                "providers": [
                  {
                    "client_id": "YOUR_GITHUB_CLIENT_ID",
                    "client_secret": "YOUR_GITHUB_CLIENT_SECRET",
                    "id": "github",
                    "provider": "github",
                    "scope": ["user:email"]
                  }
                ]
              },
              "enabled": true
            }
          }
        }
      }
    }
  }
}

See "Part 2: GitHub Social Login" below for how to get GitHub OAuth credentials.

Step 2: Apply Configuration

Option A: Import Config via Ory CLI (Fastest)

Save the merged config (OAuth2 + Identity sections) to a file and update your Ory project:

# Save your config to ory-config.json
# (Merge the OAuth2 and Identity configs from above)

# Apply to your Ory project
ory update project <project-id> \
  --workspace <workspace-id> \
  --file ory-config.json

Hint: You can export your current config with:

ory get project <project-id> \
  --workspace <workspace-id> \
  --output json > current-ory-config.json

Done! Your Ory project is now MCP-ready.

Option B: Configure via Console UI (Guided)

Prefer clicking through the UI? Each setting can be configured in the Ory Console:

2.1 Enable Dynamic Client Registration:

Go to OAuth2 & OpenID Connect → Configuration
Enable Dynamic Client Registration
Set Default Scopes: openid, offline_access

2.2 Set Token Strategy:

Go to OAuth2 & OpenID Connect → Advanced
Access Token Strategy: Choose Opaque

2.3 Enable PKCE:

Go to OAuth2 & OpenID Connect → Security
Enable PKCE for Public Clients

2.4 Set Token TTLs:

Go to OAuth2 & OpenID Connect → Token TTL
Access Token: 1h
Refresh Token: 720h (30 days)

2.5 Enable OIDC for Identity (Social Login):

Go to Identity → Social Sign-In
Click Add Provider → GitHub (or your preferred provider)
Enter Client ID and Client Secret (see GitHub setup)
Set Scopes: user:email
Save

Step 3: Create a Static OAuth2 Client

Create a static OAuth2 client for testing and for use with Claude Desktop or Claude.ai. Even if you plan to use DCR in production, having a static client helps you debug the OAuth flow without worrying about DCR-specific issues (like Bug #1).

Via Ory Console:

Go to OAuth2 & OpenID Connect → OAuth2 Clients
Click Create Client
Fill in:
- Name: "Manual Test Client"
- Grant Types: Authorization Code, Refresh Token
- Redirect URIs: http://localhost:8000/oauth/callback
- Scopes: openid, offline_access
Save and note the client_id and client_secret

Via Ory CLI:

ory create oauth2-client \
  --project {your-project-id} \
  --name "Manual Test Client" \
  --grant-type authorization_code,refresh_token \
  --response-type code \
  --scope openid,offline_access \
  --redirect-uri "http://localhost:8000/oauth/callback"

💡 Keep these credentials - you'll use them for testing in Part 4.

Part 2: GitHub Social Login (Optional but Recommended)

Expand GitHub Social Login setup

Why GitHub?

No password management to worry about
Familiar login flow for developers
One less thing to debug when testing

Step 1: Create GitHub OAuth App

Go to https://github.com/settings/developers
Click "New OAuth App"
Fill in:
- Application name: MCP Server (Dev)
- Homepage URL: https://{your-slug}.projects.oryapis.com
- Authorization callback URL: https://{your-slug}.projects.oryapis.com/self-service/methods/oidc/callback/github
Save Client ID and Client Secret

Step 2: Add to Kratos Config

Via Ory Console:

Go to Identity → Social Sign-In
Click Add Provider → GitHub
Enter:
- Client ID: (from GitHub)
- Client Secret: (from GitHub)
- Scopes: user:email
Save

Or update via JSON import (use the Identity config JSON above with your GitHub credentials).

Part 3: Your MCP Server with OAuth2

The MCP server is built using Fastify and a fork of @platformatic/mcp that adds better OAuth2 support. This fork fixes:

OIDC Discovery & OAuth Compliance (PR #97):

Original: Hardcoded /oauth/* paths didn't work with Ory Hydra's non-standard endpoints
Fixed: Auto-discovers endpoints via /.well-known/openid-configuration, adds redirect_uri support, allows excluding paths from auth (e.g., /health)

Resource Subscriptions (PR #98):

Original: No support for MCP resource subscriptions
Fixed: Adds subscription/unsubscription handlers and query parameter URI matching

DCR Proxy & Token Introspection Auth (PR #100):

Original: /oauth/register endpoint required auth (chicken-egg problem), no way to authenticate introspection requests
Fixed: DCR endpoint skips auth, adds introspectionAuth config for Ory admin API, adds DCR hooks for proxy pattern (needed for Bug #1 workaround)

Full disclosure: This is my fork, tested through building the Baume MCP server. The upstream PRs await review, but you need these fixes now.

Step 1: Install Dependencies

npm install @getlarge/fastify-mcp fastify @sinclair/typebox @fastify/type-provider-typebox

Step 2: Create Your Server

⚠️ Common Pitfall: Schema Definition

Before you write any tools, know this: @getlarge/fastify-mcp (and @platformatic/mcp) require tool input schemas to be objects at the top level. If you need mutually exclusive inputs (e.g., path OR url), wrap the union inside an object property:

// ❌ Won't work - Union at top level
inputSchema: Type.Union([Type.Object({path: ...}), Type.Object({url: ...})])

// ✅ Works - Union inside object property
inputSchema: Type.Object({
  spec: Type.Union([
    Type.Object({ path: Type.String() }),
    Type.Object({ url: Type.String({ format: 'uri' }) })
  ])
})

This also improves clarity for AI clients (ChatGPT, Claude) that sometimes struggle with flat union schemas. Thank me later.

File: src/server.ts

import Fastify from 'fastify';
import mcpPlugin from '@getlarge/fastify-mcp';
import { Type } from '@sinclair/typebox';

const fastify = Fastify({ logger: true });

fastify.get('/health', async () => ({ status: 'ok' }));

// Register MCP plugin with OAuth2 config
await fastify.register(mcpPlugin, {
  authorization: {
    enabled: true,
    authorizationServers: ['https://{your-slug}.projects.oryapis.com'],
    resourceUri: 'http://localhost:8000',
    excludedPaths: ['/health'],
    tokenValidation: {
      // Using introspection for opaque tokens
      introspectionEndpoint:
        'https://{your-slug}.projects.oryapis.com/admin/oauth2/introspect',
      // For Ory Network, authenticate introspection with API key:
      introspectionAuth: {
        type: 'bearer',
        token: process.env.ORY_API_KEY,
      },
      validateAudience: false, // See "Bug #4: Empty JWT Audience"
    },
  },
});

fastify.mcpAddTool(
  {
    name: 'hello',
    description: 'Say hello with user context',
    inputSchema: Type.Object({
      name: Type.String(),
    }),
  },
  async (input, context) => {
    const userId = context.authContext?.userId;
    return {
      content: [
        {
          type: 'text',
          text: `Hello ${input.name}! Your user ID: ${userId}`,
        },
      ],
    };
  },
);

await fastify.listen({ port: 8000, host: '0.0.0.0' });
console.log('🚀 MCP Server running on http://localhost:8000');

Step 3: Start Your Server

The Five Bugs I Hit (And Their Fixes)

War stories section — I'm listing these in order of severity, so if you're blocked, start from the top.

Bug #1 blocks all Claude clients (DCR validation)

Bug #2 blocks Claude Code CLI specifically (scope parameter)

Bugs #3-5 are configuration issues you'll hit along the way

Bug #1: All Claude Clients Reject DCR Responses with Empty URI Fields

This was the first wall I hit. Dynamic Client Registration succeeds on Hydra's side — the client gets created, logs look fine. Then every Claude client (Code CLI, Claude.ai, Claude Desktop) crashes with a validation error: client_uri, logo_uri, tos_uri, or contacts must be parseable/valid.

I dug into Hydra's DCR response and found the problem:

{
  "client_id": "...",
  "client_secret": "...",
  "client_uri": "", // Empty string fails Claude's Zod schema
  "contacts": null, // Null fails array validation
  "logo_uri": "",
  "policy_uri": "",
  "tos_uri": ""
}

Claude's Zod schema expects these fields to be either valid URLs (for *_uri fields), arrays (for contacts), or omitted entirely — not empty strings or null.

Status: Open issue #13685

This affects all Claude clients, not just Claude Code CLI. That makes it different from Bug #2 (scope parameter), which only hits the CLI.

The frustrating part: you can't configure Ory Hydra to omit these fields. They're part of the DCR spec, and Hydra includes them even when empty. So I built a workaround.

Solution: DCR Proxy

A lightweight proxy between Claude and Hydra that strips the problematic fields before Claude sees them. @getlarge/fastify-mcp supports this as a built-in hook, so the proxy runs in the same process as your MCP server — no separate deployment needed.

// DCR Proxy hook in @getlarge/fastify-mcp
// Registered as client_registration_url in your Ory OIDC discovery config

app.post('/oauth2/register', async (req, res) => {
  // Forward DCR request to Hydra
  const hydraResponse = await fetch(
    'https://{slug}.projects.oryapis.com/oauth2/register',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(req.body),
    },
  );

  const client = await hydraResponse.json();

  // Remove fields that are empty strings or null
  const cleanedClient = Object.fromEntries(
    Object.entries(client).filter(([_, value]) => {
      // Keep non-empty strings, non-null values
      return value !== '' && value !== null && value !== undefined;
    }),
  );

  res.json(cleanedClient);
});

Configure Ory to use the proxy:

In your Ory project config, set the DCR endpoint to your MCP server's proxy endpoint:

{
  "webfinger": {
    "oidc_discovery": {
      "client_registration_url": "https://your-mcp-server.com/oauth2/register"
    }
  }
}

Note: Ory Network allows customizing the client_registration_url in the OIDC discovery document. Set it to undefined to hide DCR entirely (if you only use static clients).

Why this works: Claude never sees the empty URI fields, so Zod validation passes 🫢.

Implementation reference: See the DCR proxy hook in fastify-mcp or its usage in the Baume MCP server

You could also consider using placeholder URLs (e.g., https://example.com) instead of omitting fields, but omitting is cleaner and avoids confusion.

Bug #2: Claude Code CLI Missing Scope Parameter

As of January 2026, Claude Code (CLI) has a known bug (since July 2025, tagged oncall) where it doesn't send the scope parameter during OAuth2 authorization, causing the flow to fail entirely. Use Claude.ai or Claude Desktop instead until Anthropic fixes this.

Server-side mitigation attempts (all failed):

Injecting scopes in DCR response → Claude Code ignores it
Using WWW-Authenticate scope parameter → Requires initial token (chicken-egg problem)
Ory default scopes → Only works with client_credentials grant, not authorization_code

How ironic, Anthropic wrote the MCP Authorization spec that requires proper scope handling, but Claude Code CLI doesn't implement it.

Bug #3: Token Validation Configuration Mismatch

I kept getting this error:

The token is malformed. (error code: FAST_JWT_MALFORMED)

It took me some time to realize my MCP server was trying to parse an opaque token as a JWT (using JWKS token validation). Opaque is Hydra's default strategy — and I'd forgotten that when configuring the server.

Understanding Token Validation Options

Hydra supports two token strategies:

Strategy	Token Format	Validation Method	Trade-offs
opaque (recommended)	Random string (`ory_at_...`)	Introspection endpoint	✅ Immediate revocation ✅ Better security ❌ Network call per request
jwt	JSON Web Token (`eyJhbGci...`)	JWKS (signature verification)	✅ Fast (JWKS response is cached) ❌ Can't revoke before expiry ❌ Exposed claims

For this guide and production, I recommend opaque tokens because:

You can revoke tokens immediately (logout, compromised tokens)
Ory's introspection is fast
No JWT parsing vulnerabilities
Token contents stay server-side

Your MCP server must use the matching validation method:

If using opaque tokens (recommended):

authorization: {
  tokenValidation: {
    introspectionEndpoint: 'https://{project}.projects.oryapis.com/admin/oauth2/introspect',
    // For Ory Network, authenticate with API key:
    introspectionAuth: {
      type: 'bearer',
      token: process.env.ORY_API_KEY
    }
    // Local Hydra: no auth needed if admin API is on localhost
  },
}

If using JWT tokens:

authorization: {
  tokenValidation: {
    jwksUri: 'https://{project}.projects.oryapis.com/.well-known/jwks.json',
    // Validates JWT signature locally - no network call
  },
}

Setting Hydra's token strategy:

# For opaque tokens (recommended)
ory patch oauth2-config \
  --project <project-id> \
  --replace "/strategies/access_token=opaque"

# For JWT tokens (if you prefer local validation)
ory patch oauth2-config \
  --project <project-id> \
  --replace "/strategies/access_token=jwt"

Bug #4: Empty JWT Audience (RFC 8707 Missing)

Token validation kept failing with this:

Audience validation failed: expected [http://localhost:8000], got []

The MCP spec is clear — clients MUST implement Resource Indicators (RFC 8707). That means sending a resource parameter during authorization:

GET /oauth2/auth?...&resource=http://localhost:8000

This binds the token to a specific MCP server via the JWT aud claim. Except Claude.ai doesn't send it (as of Jan 2026). So the audience comes back empty, and validation fails.

Workaround: Disable audience validation:

tokenValidation: {
  validateAudience: false, // Until Claude.ai implements RFC 8707
}

⚠️ Security warning for multi-tenant deployments: Tokens issued by your Ory instance can technically be used against any MCP server using the same issuer. For single-tenant deployments, this is acceptable. For multi-tenant, you must add validation (e.g., check client_id against known registrations, or validate custom claims).

Status: Pending Claude.ai update to support RFC 8707.

Bug #5: Ory Elements Consent Error (False Positive)

This one wasted my time because the real blocker was Bug #3 (token validation). I didn't know that yet. After clicking "Accept" on the consent screen, Ory Elements throws:

Unhandled Promise Rejection: Error: [Ory/Elements]: OAuth2 consent flow not completed.

Except... the flow actually succeeds. Claude receives a valid authorization code, tokens work fine, everything is functional. The UI just shows an error because Ory Elements doesn't handle the redirect properly.

Ory fixed the issue #587, so it should not get in your way in future releases.

Part 4: Testing the Full OAuth2 Flow

Programmatic Testing with Hydra's Admin API

You could test manually: generate a PKCE challenge, open the auth URL in a browser, click through GitHub login, copy the code from the callback, exchange it with curl... but that gets old fast.

A better approach: use Hydra's Admin API to accept login and consent programmatically — no browser, no identities, no clicking. This is what I use in my e2e tests.

The flow looks like this:

Start the auth flow — GET /oauth2/auth?client_id=...&scope=openid+offline_access&...
Accept login via Admin API — PUT /admin/oauth2/auth/requests/login/accept with a synthetic subject (no real user needed)
Accept consent via Admin API — PUT /admin/oauth2/auth/requests/consent/accept granting the requested scopes
Exchange the code — POST /oauth2/token as usual

Steps 2 and 3 are the trick — Hydra's Admin API lets you skip the browser entirely. You get a real authorization code and real tokens, without any identity provider involved.

Here's the full flow against Ory Network — client creation, PKCE auth code exchange, token introspection, and authenticated MCP calls:

Want the test script? Hit me up — I have a standalone Node.js script that runs this entire flow against Ory Network's Admin API, no browser needed.

If you see your user ID in the response, OAuth2 is working.

What About Token Refresh?

In our Ory Hydra setup, access tokens expire after 1 hour. The MCP spec says the client handles refresh — your server returns 401 on expiry, and the client uses its refresh token to obtain a new access token from Hydra. A draft section formalizes this, but it's not in the released 2025-11-25 spec yet.

In practice, don't count on it working smoothly. The Python SDK has a P0 bug where get_access_token() returns stale tokens after refresh, and ChatGPT enters a reconnect loop instead of refreshing after long idle periods. @getlarge/fastify-mcp handles the server side (proper 401s with WWW-Authenticate headers), but whether each client refreshes correctly is out of your hands.

Security Checklist

Before going live:

Ory Network:

[ ] Configure CORS properly (don't use * in production)
[ ] Set token TTLs appropriate for your use case

MCP Server:

[ ] Enable HTTPS
[ ] Re-enable audience validation once Claude.ai implements RFC 8707
[ ] Rate limit the DCR proxy endpoint (anyone can register unlimited clients)
[ ] Add rate limiting per user
[ ] Set up request logging and error monitoring
[ ] Add health checks and uptime monitoring
[ ] Rotate your Ory API key periodically

What About ChatGPT?

I wasn't planning to test ChatGPT, but after hitting so many bugs with Claude's OAuth2 implementation, I got curious. Turns out ChatGPT Web App handles OAuth2 better than Claude Code.

ChatGPT Web App (Tested 2026-01-29)

Full OAuth2.1 with DCR just works. DCR flow is clean — no phantom scopes, proper scope handling, no false errors on redirect. It even surfaces rich tool metadata (PUBLIC WRITE, OPEN WORLD, DESTRUCTIVE annotations) with per-tool auth support.

To try it yourself: go to ChatGPT web, enable Developer Mode in settings, add your MCP server URL, and the OAuth flow triggers automatically. Complete login + consent via Ory Hydra, and ChatGPT manages token storage and refresh from there — though after long idle periods it can break into a reconnect loop instead of refreshing.

Your server doesn't need any ChatGPT-specific config. It just needs /.well-known/oauth-protected-resource and proper WWW-Authenticate errors on unauthorized requests — same as Claude, and @getlarge/fastify-mcp handles both.

Codex VSCode Extension (Tested 2026-01-29)

No luck here. Codex has a two-tier system: recommended servers (Linear, Notion, Figma) get full OAuth with an "Install and authenticate" button, but custom servers only get a toggle — no OAuth flow.

You can work around it with bearer tokens in ~/.codex/config.toml:

[mcp_servers.your-server]
url = "https://your-server.com/mcp"
bearer_token_env_var = "YOUR_SERVER_TOKEN"

Then manually obtain a token via Hydra and set export YOUR_SERVER_TOKEN="ory_at_...". But the token expires after 1 hour with no auto-refresh, rotation is manual, and there's no multi-user support. Not great.

Comparison

Aspect	ChatGPT Web App	Claude Code	Codex VSCode
DCR	✅ Works cleanly	⚠️ Works with bugs	❌ Not for custom
Scope handling	✅ Respects scopes	❌ Adds phantom	N/A
Redirect flow	✅ Proper	⚠️ UI error (bug)	N/A
Tool metadata	✅ Rich annotations	❌ Basic	✅ Basic
Custom servers	✅ Full OAuth	✅ Full OAuth	❌ Bearer only
Per-tool auth	✅ Yes	❌ All-or-nothing	❌ All-or-nothing

For OAuth2 testing today: ChatGPT Web App > Claude.ai/Desktop > Claude Code CLI > Codex VSCode.

This hurts my feelings as a Claude fanboy (paying for Claude Pro Max 20x), but when OpenAI's ChatGPT Web App handles the OAuth2 specs better than Anthropic's own Claude Code — which literally references the MCP spec Anthropic wrote — something's off. The missing scope parameter bug (#4540) has been open since July 2025, tagged oncall, still unfixed. Meanwhile ChatGPT just... works.

Still, I love Claude's tools and ecosystem — when they work!

Resources

Official Documentation

GitHub Repositories

This guide's code: getlarge/claude-api-care-plugins
Fastify MCP plugin (OAuth2-ready): getlarge/fastify-mcp
Ory Hydra: ory/hydra
Ory Kratos: ory/kratos

RFCs and Standards Referenced

Full list of referenced specifications

OAuth 2.1 (draft-ietf-oauth-v2-1-13) - Core authorization framework
RFC 7591 - Dynamic Client Registration - Runtime client registration
RFC 8414 - Authorization Server Metadata - AS endpoint discovery
RFC 8707 - Resource Indicators - Token audience binding
RFC 9728 - Protected Resource Metadata - Resource server discovery
OAuth Client ID Metadata Document (draft-ietf-oauth-client-id-metadata-document-00) - CIMD

Open Issues

Issues I've encountered or created during this journey

Ory Hydra:

ory/hydra#2300 - Partial scopes in consent
ory/hydra#1618 - Default scopes discussion
ory/hydra#4061 - CIMD support request

Ory Elements:

ory/elements#587 - Consent error despite successful flow

Anthropic / Claude:

claude-code#4540 - Missing scope parameter (main issue)
claude-code#7744 - Related scopes_supported issue
claude-code#13685 - client_uri, logo_uri, tos_uri must be parseable
claude-code#2527 - Azure AD/Entra ID integration complex due to DCR requirement

Platformatic MCP:

platformatic/mcp#95 - OAuth2 subscription handling
platformatic/mcp#96 - CORS configuration issues
platformatic/mcp#99 - Authorization configuration limitations

Acknowledgments

Isabella Kohout for the article cover
Ory team for building excellent open-source auth tooling
Anthropic for the MCP specification (and for eventually fixing the bugs 😅)
Platformatic team for the original MCP server implementation for Fastify
Community who reported issues and tested edge cases

I spent a week debugging OAuth2 flows so you could skip that week. If it worked, pass it on.

Building something with this? Need help securing your MCP server? → getlarge.eu

Edouard MaleixFollow

I am a Senior Software Engineer, focusing on distributed systems, application security and developer productivity/creativity. Based in Vienna 🥐, Austria.

The MCP spec is a protocol revision maintained by the MCP project, not a ratified IETF standard — requirements may change between revisions. OAuth 2.1 itself is still an IETF draft. I reference the 2025-11-25 revision throughout this article. ↩

Ever felt like your authorization code could be easier to maintain and more flexible? How confident are you that only authorized users can access your API? When in doubt, have a look at OpenFGA! 👇

Edouard Maleix — Wed, 18 Jun 2025 04:53:39 +0000

How to Protect Your API with OpenFGA: From ReBAC Concepts to Practical Usage

Edouard Maleix for This is Learning ・ Jun 15

#tutorial #openfga #authorization #security

How to Protect Your API with OpenFGA: From ReBAC Concepts to Practical Usage

Edouard Maleix — Sun, 15 Jun 2025 19:12:59 +0000

Another story, another article. A client asked me recently:

🗣️ Can we add temporary permissions for a group of users assigned to a maintenance task, while it's ongoing?

It should be simple enough, right? Yes, until I examined the authorization code behind the API and found a 500-line function checking user roles and groups, time windows, resource ownership, and various business rules. 😶‍🌫️

Unlike authentication (who is accessing the system), where we have OIDC, JWT, and other established standards and patterns, authorization (what they can do) often forces us into custom implementations.

🫷You might argue that OAuth 2.0 cover authorization, but they focus on third-party access, not complex and dynamic authorization patterns.

The OWASP Top 10 API Security Risks lists Broken Object Level Authorization as the #1 risk, showing us how common it is to expose sensitive data due to poor authorization checks.
Is it far-fetched to think that the complexity of authorization logic contributes to this risk?

Each new policy adds another conditional branch, another database join, another custom role, another edge case that breaks during the next feature request. The authorization flow becomes a spaghetti bowl and even experienced developers hesitate before touching it.

Traditional approaches quickly hit walls:

RBAC works until you need "sometimes" permissions
ABAC offers flexibility but becomes a rule engine nightmare
Database queries slow to a crawl as your permission matrix grows

What if there is a better way? A way that lets you express complex relationships without messy code or performance hits? 🤔

My exploration for a better paradigm started with Ory Keto:

Edouard Maleix

May 16 '24

Integrate Ory in a NestJS application

#tutorial #javascript #nestjs #ory

Comments

32 min read

It introduced me to Google's Zanzibar paper and the concept of Relation-Based Access Control (ReBAC).

Zanzibar: A Global Authorization System - Presented by Auth0

Zanzibar handles authorization for all of Google’s products, allows teams to specify their unique authorization models, globally replicates authorization data, and responds to access checks blazing fast.

zanzibar.academy

This time, I needed more flexibility to introduce contextual relationships. That "simple" feature request led me to OpenFGA — a richer implementation of Zanzibar's principles that extends ReBAC with powerful features like contextual-based conditions, attribute-based access, and a simple query language.

And since you might be familiar with this story, I'll share with you my learning journey, starting from the concepts and terminology, through practical examples and considerations, to real-world usage of OpenFGA.

✅ The Authorization Problem
📍 Why OpenFGA? ← You are here
⬜ ReBAC and OpenFGA concepts
⬜ OpenFGA in Action
⬜ Testing permissions with OpenFGA CLI
⬜ Adoption Challenges and Strategies

Why OpenFGA [▓░░░░░░░]

Before I grab your attention and your brain 🧠 with the ReBAC concepts and how OpenFGA implements them, let me explain why I chose OpenFGA over other solutions.

It Matches How You Think

Expressive Relationships

Cat owners own cats. Sitters sit cats. Admins administrate. The authorization model mirrors reality instead of forcing you into artificial role hierarchies. Demo

Direct relations

Implied relations

Time Works Automatically

No more "grant permission at 9 AM, revoke at 5 PM" cron jobs. Time-based access happens naturally through conditions.
Grant permissions only when conditions are met—like during scheduled hours.
Demo

🤝 Yes! My client is going to love this.

Status Drives Decisions

Your app's workflow probably includes some entities' states (e.g., pending, active, completed). OpenFGA uses these attributes directly for permissions instead of requiring separate access control flags. Demo

Queries, Not Just Checks

Traditional systems answer "Can Alice do X?" OpenFGA also answers "What can Alice do?" and "Who can do X?" This opens opportunities for features like smart dashboards and permission audits.
Demo

Tuple Queries from OpenFGA playground Who has the right to feed Romeo?

Scale Like Google

Google's Zanzibar (which inspired OpenFGA) handles billions of authorization checks daily. Your application(s) probably won't hit those numbers, but it's nice to know you won't hit a wall due to a poorly performing authorization system.

☝️ In my tests, OpenFGA performed slightly better than custom database lookups for complex relationships (both based on PostgreSQL).

Great Documentation and CLI Tools

I can't deny it, OpenFGA has a steep learning curve, but its documentation is complete and well-structured. It covers everything from basic concepts to advanced usage patterns until deployment strategies.

The CLI tools make it easy to manage your authorization model and test your policies.

Business Backing

OpenFGA is open-source and Okta is funding it, this ensures a long-term viability and support. On one side, you can always deploy it on your own infrastructure, and the community is growing rapidly. On the other side, Okta has strong competitors like OSO, Ory Keto or AWS Cedar, so they have a vested interest in making OpenFGA a successful product extending what Auth0 has to offer.

Deployment Flexibility

OpenFGA can be deployed in various ways, depending on your needs:

Self-hosted: Use Docker Compose to get started locally, Kubernetes for full control and Terraform to orchestrate your infrastructure.
Managed service: Use Auth0's FGA offering for a hassle-free experience.

Observability and Debugging

You can configure:

OpenTelemetry for traces collection on the client and the server side.
Prometheus for metrics collection.

This makes it easier to monitor your authorization system with open standards and integrate with your existing observability stack.

Simpler Code To Maintain

To illustrate this, I'm using Typescript to check if a user can update a cat sitting arrangement with both approaches: a plain database lookup and an OpenFGA check.

Database Lookup

async function isSystemAdmin(userId: string): Promise<boolean> {
  const user = await userRepository.findById(userId);
  if (!user) return false;
  return user.role === 'admin';
}

async function checkCatSittingUpdatePermission(
  userId: string,
  sittingId: string
): Promise<boolean> {
  const sitting = await catSittingRepository.findById(sittingId);
  if (!sitting) return false;

  const cat = await catRepository.findById(sitting.catId);
  if (!cat) return false;

  const isOwner = cat.ownerId === userId;
  const isSitter = sitting.sitterId === userId;
  const isAdmin = () => await isSystemAdmin(userId);
  const isPending = () =>
    sitting.status === 'requested' && new Date(sitting.startTime) > new Date();

  return isOwner || (isSitter && isPending()) || isAdmin();
}

OpenFGA Check

async function checkCatSittingUpdatePermission(
  userId: string,
  catSittingId: string
): Promise<boolean> {
  const openfgaClient = new OpenFgaApi({
    apiUrl: process.env.OPENFGA_API_URL,
  });

  const request: CheckRequest = {
    tuple_key: {
      user: `user:${userId}`,
      relation: 'can_update',
      object: `cat_sitting:${catSittingId}`,
    },
    context: {
      current_time: new Date().toISOString(),
    },
  };

  const { allowed } = await openfgaClient.check(
    process.env.FGA_STORE_ID,
    request
  );
  return !!allowed;
}

Does it need a lot of explanation? The OpenFGA version is objectively cleaner, more maintainable, and scales better as your authorization logic grows.

ReBAC and OpenFGA concepts [▓▓▓░░░░]

I'll walk you through ReBAC using PurrfectSitter ©, a cat sitting app where owners find sitters. Real problems, real solutions.
As trivial as it sounds, this example shows:

Role-based access control (RBAC) for admins
Attribute-based access control (status-driven permissions)
Time-based access control
Resource ownership and management

Three Building Blocks

ReBAC builds authorization from three simple pieces:

Types: Entities in Your App

type user
type system
type cat
type cat_sitting
type review

These map to your app's core entities:

user: 👤 People using your app
system: 🏢 Admin access controls
cat: 🐱 Furry clients needing care
cat_sitting: 🏠 A sitting arrangement
review: 📝 Post-sitting feedback

Each type will declare relationships with other types - in the type definition.

ℹ️ In Ory Keto, these are called namespaces.

Objects: Instances of Types

In OpenFGA, an object is an instance of a type. For example:

user:bob: A specific user named Bob
cat:romeo: A specific cat named Romeo
system:development: The development environment
cat_sitting:1: The first cat sitting arrangement
review:1: The first review

Objects are the concrete entities your users interact with.

Users: The Actors

A user is an entity that is related to objects in your system. In our app, users can be:

People (like Bob)
Systems (like the PurrfectSitter development environment)
Cats (like Romeo)

ℹ️ In Ory Keto, these are called subjects. I believe subject is less ambiguous than user, but OpenFGA uses user, so we will too.

Relations: How Things Connect

A relation defines how users interact with objects. For example:

user:bob owner cat:romeo: Bob is the owner of Romeo
user:anne sitter cat_sitting:1: Anne is the sitter for the first cat sitting arrangement

Each relation (e.g., admin) evaluation logic is defined in the relation definition (e.g., [user]).

type system
  relations
    define admin: [user]

type cat
  relations
    define owner: [user]
    define admin: admin from system
    define can_manage: owner or admin
    define system: [system]

type cat_sitting
  relations
    define active_sitter: [cat_sitting#sitter with is_active_timeslot]
    define can_post_updates: owner or active_sitter
    define can_review: [cat#owner with is_cat_sitting_completed]
    define cat: [cat]
    define owner: owner from cat
    define sitter: [user]

‼️ For the sake of this example, we will assume that cats are owned by humans. We all know that, in reality, cats own us, not the other way around.

OpenFGA computes relationships in several ways:

Direct:
- system.admin — A user can be an admin of the system
- cat.owner — A user can be a cat owner
- cat.system — A system can be assigned to a cat
- cat_sitting.sitter — A user can be a sitter for a cat_sitting
Implied:
- cat.admin: admin from system — An admin is a user from the system
- cat_sitting.owner: owner from cat — The cat_sitting owner is the cat owner
Union:
- cat.can_manage — either the cat owner or an admin from the system can manage the cat
- cat_sitting.can_post_updates — either the cat_sitting owner or an active_sitter can post updates
Conditional:
- cat_sitting.active_sitter — Conditional relation between user and cat_sitting based on the outcome of the is_active_timeslot condition
- cat_sitting.can_review — Conditional relation between user and cat_sitting based on the outcome of the is_cat_sitting_completed condition

There are even more ways to express relationships, such as exclusion, intersection and nesting, you can find the complete configuration language reference in the OpenFGA documentation.

The Complete Authorization Model

The ensemble of types and relations definitions forms the authorization model.
Here, the PurrfectSitter's authorization model in OpenFGA's configuration language (Domain-Specific Language for the purist), defines how users interact with cats, cat sittings, and reviews.

model
  schema 1.1

type user

type system
  relations
    define admin: [user]

type cat
  relations
    define admin: admin from system
    define can_manage: owner or admin
    define owner: [user]
    define system: [system]

type cat_sitting
  relations
    define admin: admin from system
    define active_sitter: [cat_sitting#sitter with is_active_timeslot]
    define pending_sitter: [cat_sitting#sitter with is_pending_timeslot]
    define can_post_updates: owner or active_sitter
    define can_delete: admin or owner or pending_sitter
    define can_view: admin or owner or sitter
    define can_update: admin or owner or pending_sitter
    define can_review: [cat#owner with is_cat_sitting_completed]
    define cat: [cat]
    define owner: owner from cat
    define sitter: [user]
    define system: [system]

type review
  relations
    define admin: admin from system
    define author: owner from cat_sitting
    define can_delete: admin or author
    define can_edit: admin or author
    define can_view: [user, user:*]
    define cat: cat from cat_sitting
    define cat_sitting: [cat_sitting]
    define subject: sitter from cat_sitting
    define system: [system]

condition is_active_timeslot(current_time: timestamp, end_time: timestamp, start_time: timestamp) {
  current_time >= start_time && current_time <= end_time
}

condition is_pending_timeslot(current_time: timestamp, start_time: timestamp) {
  current_time < start_time
}

condition is_cat_sitting_completed(cat_sitting_attributes: map<string>, completed_statuses: list<string>) {
  cat_sitting_attributes["status"] in completed_statuses
}

Notice how readable, yet compact, this is — no complex SQL joins or nested conditions. The model captures business logic naturally.

✅ Checkpoint: Can You Answer These?

Before moving on, make sure you can answer:

What's the difference between a user and an object?
How do relations differ from roles?
When would you use indirect relationships?

Answers

User vs Object: A user is an entity (like a person), while an object is an instance of a type (like a specific cat or cat sitting arrangement). Users interact with objects through relations.
Relations vs Roles: Relations define how entities connect (like "owner of cat"), while roles are broader categories (like "admin" or "sitter") that can have multiple relations.
Indirect Relationships: Use these when you want to derive permissions from other relationships, like "can a sitter post updates if they are also the owner?" This allows for more flexible and dynamic permission checks.

OpenFGA in Action [▓▓▓░░░░]

Let's test our model with real scenarios. I use the OpenFGA CLI to initialize the authorization model, create relation tuples, check the permissions and run some querie but you can use any other client SDK.

Save some time, create a GitHub codespace

It will provide you a ready-to-use environment with all dependencies installed and external services running, so you can focus on running the examples in this article.

Setup OpenFGA

1. Creating a Store and a Model

First, create a store:

Then create the authorization model in the new store:

⚠️ If you are using Codespaces, specify the API path with

the flag --api-url http://openfga:8080

the environment variable FGA_API_URL=http://openfga:8080

2. Creating Basic Relationships

Bob owns Romeo, Anne sits for him. Simple.

3. Admin Powers

Jenny becomes a system admin who can manage any cat — traditional RBAC within ReBAC.

4. Time Magic

Anne's permissions activate and deactivate automatically based on time. No cron jobs, no cleanup code — the authorization system handles it.

5. Status-Driven Access

Reviews only make sense after sitting ends. OpenFGA enforces this business rule automatically, ABAC style.

6. Creating and Checking Review Permissions

Create a review and check who can edit or delete it. OpenFGA's query language shines here, allowing you to check permissions and also list objects a user can interact with.

7. Making the Review Public

Control visibility using wildcards.

Explore Relationships with OpenFGA Playground

You can visualize the relations graph and run queries in the OpenFGA's Playground.
I find it a great way to discover and understand relationships in your model and test queries interactively.

💡 If you are using Codespaces, just open http://localhost:8082/playground in your browser.

Testing permissions with OpenFGA CLI [▓▓▓▓░░░]

Another one of OpenFGA's strengths, is its built-in testing capabilities. The CLI provides a declarative way to test authorization models without writing application code.

Declarative Testing with YAML

Define tests in YAML and run with a single command:

fga model test --tests store.fga.yml

...and forget about all the commands above 🙂. The store.fga.yml file contains everything you need to create the model and tuples, and run the tests before writing application code!

Let's look at the store.fga.yml file that tests our PurrfectSitter model:

The authorization model

This is the model we defined earlier, but in YAML format for the OpenFGA CLI:

model: |
  model
    schema 1.1

  # Our full model definition goes here...

ℹ️ The model section is the same as the one we defined earlier, but in YAML format for the OpenFGA CLI.

The tuples

This section defines the relationships (tuples) in our model. Each tuple represents a relationship between a user and an object, along with the relation type.

model:
  # ...
tuples:
  - user: user:jenny
    relation: admin
    object: system:development

  - user: user:bob
    relation: owner
    object: cat:romeo

  - user: system:development
    relation: system
    object: cat:romeo

  - user: cat:romeo
    relation: cat
    object: cat_sitting:1

  - user: user:anne
    relation: sitter
    object: cat_sitting:1

  - user: cat_sitting:1#sitter
    relation: active_sitter
    object: cat_sitting:1
    condition:
      name: is_active_timeslot
      context:
        start_time: '2023-01-01T00:00:00Z'
        end_time: '2023-01-02T00:00:00Z'

  - user: cat:romeo#owner
    relation: can_review
    object: cat_sitting:1
    condition:
      name: is_cat_sitting_completed
      context:
        completed_statuses: ['completed']

  - user: system:development
    relation: system
    object: review:1

  - user: cat_sitting:1
    relation: cat_sitting
    object: review:1

  - user: user:*
    relation: can_view
    object: review:1

The tests

This section defines the tests that will be run against the model and tuples. Each test checks specific permissions or relationships.

The example demonstrates several test types:

Basic permission checks: Simple assertions about relationships
Contextual checks: Testing time-based permissions
Attribute-based checks: Testing permissions depending on object attributes
List objects: Finding objects a user has relationships with
List users: Finding users with relationships to an object

model:
  # ...
tuples:
  # ...
tests:
  - name: Test basic relations
    check:
      - user: user:anne
        object: cat_sitting:1
        assertions:
          sitter: true

      - user: user:bob
        object: cat_sitting:1
        assertions:
          owner: true

  - name: Test role access
    check:
      - user: user:jenny
        object: cat:romeo
        assertions:
          can_manage: true

      - user: user:bob
        object: cat:romeo
        assertions:
          can_manage: true

      - user: user:anne
        object: cat:romeo
        assertions:
          can_manage: false

  - name: Test temporal access
    check:
      - user: user:anne
        object: cat_sitting:1
        context:
          current_time: '2023-01-01T00:10:00Z'
        assertions:
          active_sitter: true

      - user: user:anne
        object: cat_sitting:1
        context:
          current_time: '2023-01-04T00:00:00Z'
        assertions:
          active_sitter: false

  - name: Test attribute access
    check:
      - user: user:bob
        object: cat_sitting:1
        context:
          cat_sitting_attributes:
            status: 'completed'
        assertions:
          can_review: true

      - user: user:bob
        object: cat_sitting:1
        context:
          cat_sitting_attributes:
            status: 'in_progress'
        assertions:
          can_review: false

  - name: Test the cat sitting that anne is sitting
    list_objects:
      - user: user:anne
        type: cat_sitting
        context:
          current_time: '2023-01-01T00:00:01Z'
        assertions:
          active_sitter:
            - cat_sitting:1
          sitter:
            - cat_sitting:1

  - name: Test the review that bob can edit
    list_objects:
      - user: user:bob
        type: review
        assertions:
          can_edit:
            - review:1

  - name: Test that reviews are public
    list_users:
      - object: review:1
        user_filter:
          - type: user
        assertions:
          can_view:
            users:
              - user:*

👋 You can find store.fga.yml in the demo repository.

Testing During Adoption

These testing capabilities help when adopting OpenFGA:

Validate models against business rules
Verify permissions match the old system during migration
Compare results with your existing system in shadow mode
Prevent regressions with CI pipeline tests

Including tests in your workflow reduces authorization errors and builds confidence in your implementation.

✅ Checkpoint II: Can You Answer These?

Have you read carefully the previous sections? If so, you should be able to answer:

Can you list objects a user has relationships with?
Can you list users with relationships to an object?
Can you make an object public to all users?

Answers

List Objects: Yes, you can use the list-objects command to find objects a user has relationships with, like finding all cat sittings where a user is an active sitter.
List Users: Yes, if you have a relationship that connects users to objects, you can use the list-users command to find users with relationships to an object, like finding all users who can view a specific review.
Public Objects: Make an object public by adding a relation that allows all users to access it, like granting user:* permission on the object as I showed you in this example

Adoption Challenges and Strategies [▓▓▓▓▓▓░]

As good as this tool is, adopting OpenFGA in existing systems presents challenges.

Mental Model Shift

ReBAC requires a paradigm shift for developers:

Mental model adjustment: Developers familiar with RBAC or ABAC need time to think in relationships.
Training investment: Workshops and examples help teams translate existing rules into relationship models.

Data Synchronization

This is probably the most challenging aspect of adopting OpenFGA, especially if you have an existing database with complex permissions.

Dual writes: Applications must write to both their database and OpenFGA.
Synchronization strategies:
- Event-driven synchronization through message queues
- Centralized hooks for database operations
- Transactional outbox pattern for consistency
- Background jobs for existing data

Read this excellent article 👇 about dual writes in distributed systems. It will surely help you understand strategies for synchronizing data between your applications' DB and OpenFGA.

Handling the Dual-Write Problem in Distributed Systems | Auth0

The dual-write problem exists in distributed systems. Let's look at what it is and some of the most common strategies to mitigate it usin...

auth0.com

Progressive Adoption

It's going to be hard (and unwise) to convince your team to rewrite the entire authorization logic in OpenFGA, big-bang refactoring style. Instead, consider a progressive adoption strategy:

1. Start with Coarse-Grained Permissions

Begin with your existing structure:

Replicate your current RBAC model
Add organization-level permissions
Gradually introduce finer-grained controls

2. Shadow Mode Implementation

Before switching fully:

Run existing authorization alongside OpenFGA
Compare results to identify discrepancies
Build confidence before making the switch

3. Use Contextual Tuples for Hybrid Implementations

Reduce synchronization burden:

Send data as contextual tuples initially
Gradually move to persistent relationship tuples
Use contextual tuples for frequently changing data

ℹ️ Read more about this technique in the OpenFGA documentation.

Managing Organizational Adoption

For large organizations:

Start with a single application where OpenFGA delivers immediate value
Use modular models for independent team control
Leverage access control for team-specific credentials

Your Next Move [▓▓▓▓▓▓▓]

Complex policies doesn't have to mean complex code. OpenFGA's ReBAC model simplifies permissions into relationships, making your authorization logic more maintainable and scalable.

Ready to get started? Here's your roadmap:

Read in details the PurrfectSitter's authorization model
Draw inspiration from the Purrfect Sitter Fastify API
Adapt it to your domain
Watch complex permission logic become simple relationship definitions.
Get in touch with me for some deep-dive into performance characteristics, monitoring, and production deployment patterns 😉
If you want to show your appreciation, give those repositories a ⭐️ on GitHub. 👇

getlarge / purrfect-sitter

A cat sitting management application to showcase OpenFGA

Purrfect Sitter

A cat sitting application with dual authorization strategies This is the support project for the How to Protect Your API with OpenFGA article.

An anonymous developer surrounded by cats

Architecture

Core Application

Fastify-based API
User authentication with Ory Kratos
Core models: User, Cat, CatSitting, Review
TypeBox for JSON Schema validation
Drizzle ORM for database access
OpenFGA for fine-grained authorization

NX Workspace Structure

apps/
  purrfect-sitter/       # Main Fastify application
  purrfect-sitter-e2e/   # End-to-end tests

libs/                    # Domain-specific libraries
  database/              # Database schema and repositories
  models/                # DTOs and validation schemas
  auth/                  # Authentication and authorization
  cats/                  # Cats domain business logic
  cat-sittings/          # Cat sittings domain business logic
  reviews/               # Reviews domain business logic

Authorization Strategies

This application implements two authorization strategies that can be toggled via environment variables:

Database Lookups (AUTH_STRATEGY=db)
- Traditional database queries to check permissions
- Uses JOINs and WHERE clauses for relationship checks
- Direct SQL…

View on GitHub

openfga / openfga

A high performance and flexible authorization/permission engine built for developers and inspired by Google Zanzibar

OpenFGA

OpenFGA is a high-performance, flexible authorization/permission engine inspired by Google Zanzibar It helps developers easily model and enforce fine-grained access control in their applications.

Highlights

⚡ High-performance, developer-friendly APIs (HTTP & gRPC)
🔌 Flexible storage backends (In-Memory, PostgreSQL, MySQL, SQLite beta)
🧰 SDKs for Java, Node.js, Go, Python, .NET
🌐 Several additional SDKs and tools contributed by the community
🧪 CLI for interacting with an OpenFGA server and testing authorization models
🌿 Terraform Provider for configuring OpenFGA servers as code
🎮 Playground for modeling and testing
🛠 Can also be embedded as a Go library
🤝 Adopted by Auth0, Grafana Labs, Canonical, Docker, Agicap, Read.AI and others

Quickstart

Important

The following steps are meant…

View on GitHub

Your future self will thank you for choosing relationships over nested IF statements.

Edouard MaleixFollow

I am a Senior Software Engineer, focusing on distributed systems, application security and developer productivity/creativity. Based in Vienna 🥐, Austria.

References

Building Single Executable Applications with Node.js

Edouard Maleix — Mon, 17 Mar 2025 10:50:00 +0000

"Can we upgrade to the latest Node.js version?"

A few months ago, I did not imagine that this seemingly innocent question from a client would bring me so deep into the world of single executable applications, a.k.a. SEA, a.k.a. executable binaries.

Their team had been using PKG to package Node.js applications into standalone executables, but then they hit a roadblock - PKG has been deprecated. While the community fork had kept pace with Node.js evolution (even working on Node.js v22), the constant changes to Node.js internals made maintaining these patches challenging. Each new Node.js version required adapting to internal changes, creating an ongoing maintenance effort that added complexity to their deployment pipeline.

That's when I remembered hearing about Node.js Single Executable Applications (SEA) - a native feature. As someone who's spent years optimizing deployment pipelines and container strategies, I knew I had to explore this promising alternative.

In this article, I'm sharing what I've learned about SEA, a feature that fundamentally shifts how we package and distribute Node.js applications. If you've encountered:

Delays waiting for packaging tools to support new Node.js versions
Complex configuration requirements for native modules
The maintenance burden of keeping dependencies versions and build tools in sync with runtime
The search for lighter, more portable deployment artifacts

...then you'll find this exploration valuable.

I'll take you through both the technical foundations and practical implementation of SEA, showing how it can simplify your deployment strategy while making your applications more portable and secure.

Two Worlds of Application Distribution
Technical Foundation
Practical Implementation
Docker Integration
Performance Benchmarks
The Reality of Code Protection
Conclusion

Two Worlds of Application Distribution

First, I want to distinguish between each distribution method.

Traditional Node.js Deployment

The conventional approach to Node.js deployment has several limitations:

Fragmented Distribution: Source files, dependencies, and runtime are all separate pieces
Environment Dependencies: Applications only work when the target environment has the exact right setup
Configuration Fragility: Settings files must be correctly placed and formatted
Version Constraints: The correct Node.js version must be present

This creates a brittle deployment pipeline where one small misconfiguration can cause everything to fail.

Single Executable Applications Deployment

Single Executable Applications (SEA) represent a fundamental paradigm shift:

Complete Self-Containment: Code, dependencies, assets, and runtime bundled in one binary
Environment Independence: The application carries its environment with it
Protected Configuration: Settings embedded and secured within the executable
Deployment Simplicity: One file to deploy, one file to run

This approach represents a shift-left in application delivery—moving deployment concerns from operations teams into the development process. With SEA, developers take ownership of packaging the entire application environment during development rather than leaving it to deployment time.

The result? Applications that are more reliable, more secure, and significantly easier to deploy.

Technical Foundation

As a longtime Node.js developer, I was curious about how this feature was implemented. Let's peek under the hood!

The Anatomy of a SEA

A Single Executable Application builds in three distinct stages:

Collection Stage
Virtual File System Stage
Binary Integration Stage

Collection Stage

This is where things start getting interesting! The SEA tooling gathers:

JavaScript application code
JSON configuration files
Dependencies from node_modules
Native add-ons
Static assets

Virtual File System Stage

This is where the real magic happens. Instead of just bundling files, SEA creates a miniature in-memory filesystem that:

Preserves directory structures exactly as they were
Maintains file permissions
Keeps symbolic links intact
Retains original file paths
Enables fast random access

Binary Integration Stage

The final step injects our virtual filesystem into the Node.js binary:

Preserves execution ability
Maintains code signing compatibility
Enables runtime detection
Supports cross-platform formats (Mach-O, PE, ELF)

Internals

The conductor behind the SEA orchestra is a small piece of C++ code in the Node.js source.

Note This is the nerdy part, feel free to jump to the Practical Implementation if you're more interested in hands-on examples.

SEA Configuration

The node_sea.cc evolves around the SeaResource structure.

class SeaResource {
 public:
  static constexpr uint32_t kMagic = 0x1EA;  // SEA magic number
  static constexpr size_t kHeaderSize = 8;    // Size of header

  SeaFlags flags;
  std::string_view code_path;
  std::string_view main_code_or_snapshot;
  std::optional<std::string_view> code_cache;
  std::unordered_map<std::string_view, std::string_view> assets;
};

This structure shows us several critical design decisions:

Use of a magic number (0x1EA) to identify the injected program during deserialization
Support for both code and snapshots
Optional location for code cache (we'll talk about it later)
Asset storage in a key-value format

SEA Generation Process

The high-level process of the SEA creation is simple:

Read the main (bundled) script
Generate V8 snapshot if needed (I will talk about snapshot later)
Generate code cache if requested (I will talk about cache later)
Processes and includes assets
Serialize everything into a single Blob

ExitCode GenerateSingleExecutableBlob(const SeaConfig& config,
                                     const std::vector<std::string>& args,
                                     const std::vector<std::string>& exec_args) {
  std::string main_script;
  ReadFileSync(&main_script, config.main_path.c_str());

  if (static_cast<bool>(config.flags & SeaFlags::kUseSnapshot)) {
    GenerateSnapshotForSEA(...);
  }

  if (static_cast<bool>(config.flags & SeaFlags::kUseCodeCache)) {
    GenerateCodeCache(config.main_path, main_script);
  }

  std::unordered_map<std::string, std::string> assets;
  BuildAssets(config.assets, &assets);

  SeaSerializer serializer;
  serializer.Write(sea);
}

Resource Injection

SEA uses the postject library to add our VFS as a new section in the binary file format.

Different operating systems use different binary formats. Node.js support the following:

macOS uses Mach-O
Windows uses Portable Executable (PE)
Linux uses ELF (Executable and Linkable Format)

std::string_view FindSingleExecutableBlob() {
#ifdef __APPLE__
  postject_options options;
  postject_options_init(&options);
  options.macho_segment_name = "NODE_SEA";
  const char* blob = static_cast<const char*>(
      postject_find_resource("NODE_SEA_BLOB", &size, &options));
#else
  const char* blob = static_cast<const char*>(
      postject_find_resource("NODE_SEA_BLOB", &size, nullptr));
#endif
  return {blob, size};
}

Read-Only Assets

One important security feature is read-only asset access.
The implementation ensures assets remain read-only through careful API design:

Assets are stored as immutable string_views
The ArrayBuffer is created with a no-op deleter
No API exists for modifying assets once bundled

void GetAsset(const FunctionCallbackInfo<Value>& args) {
  // Validate input
  CHECK_EQ(args.Length(), 1);
  CHECK(args[0]->IsString());

  Utf8Value key(args.GetIsolate(), args[0]);
  SeaResource sea_resource = FindSingleExecutableResource();

  auto it = sea_resource.assets.find(*key);
  if (it == sea_resource.assets.end()) {
    return;
  }

  std::unique_ptr<v8::BackingStore> store = ArrayBuffer::NewBackingStore(
      const_cast<char*>(it->second.data()),
      it->second.size(),
      [](void*, size_t, void*) {},  // No-op deleter prevents modifications
      nullptr);

  Local<ArrayBuffer> ab = ArrayBuffer::New(args.GetIsolate(), std::move(store));
  args.GetReturnValue().Set(ab);
}

Load the SEA

The final step is loading the SEA and executing the bundled code:

Gets the current V8 context and environment
Finds the SEA resource using FindSingleExecutableResource()
Verifies it's not using a snapshot (CHECK(!sea.use_snapshot()))
Converts the main code into a V8 value using ToV8Value
Calls the CJS (CommonJS) run callback with the converted code (from this, you can guess that only CJS is supported!)

MaybeLocal<Value> LoadSingleExecutableApplication(
    const StartExecutionCallbackInfo& info) {
  Local<Context> context = Isolate::GetCurrent()->GetCurrentContext();
  Environment* env = Environment::GetCurrent(context);
  SeaResource sea = FindSingleExecutableResource();

  CHECK(!sea.use_snapshot());
  Local<Value> main_script =
      ToV8Value(env->context(), sea.main_code_or_snapshot).ToLocalChecked();
  return info.run_cjs->Call(
      env->context(), Null(env->isolate()), 1, &main_script);
}

Practical Implementation

I built a file management service using Fastify to demonstrate SEA capabilities in the real world. The complete source code is available in the Node-SEA Demo repository.

Hopefully, Liran Tal won't put the shame on me with this example app, no input validation, no rate limit, no auth, at least there's a path traversal check ;)

Project Structure

The project structure is simple, while representing a typical Node.js HTTP API application:

node-sea-demo/
├── src/
│   ├── main.ts                 # Entry point with SEA detection
│   ├── app/
│   │   ├── app.ts             # Fastify setup
│   │   ├── helpers.ts         # Utilities
│   │   └── routes/
│   │       └── root.ts        # API handlers
│   └── assets/                # Static files
├── sea-config.json            # SEA configuration
└── project.json              # Build configuration

Key Implementation Details

The first challenge I encountered was detecting whether we're running in a SEA environment to override the require function.

import sea from 'node:sea';

if (sea.isSea()) {
  const { createRequire } = require('node:module');
  require = createRequire(__filename);
}

const server = Fastify({
  logger: true,
  trustProxy: true,
});

When running as a SEA, require.cache is undefined! The bug is tracked here.

Another pain point was managing Fastify plugins within the SEA environment. I found explicit registration works better than auto-loading, to avoid compilation issues:

// app.ts
export async function app(fastify: FastifyInstance, opts: AppOptions) {
  await fastify.register(sensible);
  await fastify.register(fastifyMultipart, {
    limits: {
      fileSize: opts.fileSize ?? 1048576 * 10, // 10MB
    },
  });

  const assetsDir = await getAssetsDir();
  await fastify.register(fastifyStatic, {
    root: assetsDir,
    prefix: '/assets/',
  });

  await fastify.register(routes);
}

Security was another concern. Since SEA applications might also run with elevated privileges, I implemented strict path safety:

// routes/root.ts
const safePathResolve = (userPath: string, baseDir: string): string | null => {
  if (!userPath || /[/\\]/.test(userPath)) {
    return null;
  }
  try {
    const resolvedPath = path.resolve(baseDir, userPath);
    if (!resolvedPath.startsWith(path.resolve(baseDir))) {
      fastify.log.warn({ path: userPath }, 'Path traversal attempt detected');
      return null;
    }
    return resolvedPath;
  } catch (err) {
    fastify.log.error({ err, path: userPath }, 'Path resolution error');
    return null;
  }
};

Build Process

The first step in creating an SEA is properly bundling your JavaScript. I explored several bundlers and found ESBuild offers the best balance of speed and ease of use.

Bundling with ESBuild

ESBuild prepares your application for SEA packaging through CLI or build tools.

Direct ESBuild Command

npx esbuild \
    --format=cjs \
    --platform=node \
    --bundle \
    --tsconfig=apps/node-sea-demo/tsconfig.app.json \
    --outdir=dist/apps/node-sea-demo \
    --out-extension:.js=.js \
    --outfile=main.js \
    apps/node-sea-demo/src/main.ts

Each flag serves a specific purpose:

--format=cjs: SEA only works with CommonJS (no ESM yet, remember?)
--platform=node: Targets Node.js environment
--bundle: Rolls up all imports into a single file
--outfile: Specifies the output file for the bundled code

Nx ESBuild plugin Configuration

If you're using Nx (like I do), you can configure the build in your project's configuration file:

// project.json
{
  "build": {
    "executor": "@nx/esbuild:esbuild",
    "outputs": ["{options.outputPath}"],
    "defaultConfiguration": "production",
    "options": {
      "platform": "node",
      "outputPath": "dist/apps/node-sea-demo",
      "format": ["cjs"],
      "bundle": true,
      "thirdParty": true,
      "main": "apps/node-sea-demo/src/main.ts",
      "tsConfig": "apps/node-sea-demo/tsconfig.app.json",
      "assets": ["apps/node-sea-demo/src/assets/**/*"],
      "generatePackageJson": true,
      "esbuildOptions": {
        "sourcemap": true,
        "outExtension": {
          ".js": ".js"
        }
      }
    }
  }
}

Generating the Executable

After struggling with single executables builder tools like PKG, I was glad to discover Node.js's native SEA support. The configuration is refreshingly simple:

// sea-config.json
{
  "main": "dist/apps/node-sea-demo/main.js",
  "output": "dist/apps/node-sea-demo/demo.blob",
  "disableExperimentalSEAWarning": true,
  "useCodeCache": true,
  "assets": {
    "package.json": "dist/apps/node-sea-demo/package.json"
  }
}

The executable generation process varies by platform, if you are using Nx, you can make your life easier by using my plugin:

// nx.json
{
  //...
  "plugins": [
    // ...
    {
      "plugin": "@getlarge/nx-node-sea",
      "include": ["apps/**/*"],
      "options": {
        "seaTargetName": "sea-build",
        "buildTarget": "build"
      }
    }
  ]
}

.. and then run:

nx run node-sea-demo:sea-build

Otherwise, you can use the following commands for each platform, see the Node.js SEA documentation for more details:

Linux

# Generate blob
node --experimental-sea-config sea-config.json

# Copy node binary
cp $(command -v node) dist/app/node

# Inject blob
npx postject dist/app/node NODE_SEA_BLOB dist/app/demo.blob \
  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2

macOS

# Generate blob
node --experimental-sea-config sea-config.json

# Copy node binary
cp $(command -v node) dist/app/node

# Remove signature
codesign --remove-signature dist/app/node

# Inject blob
npx postject dist/app/node NODE_SEA_BLOB dist/app/demo.blob \
  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 \
  --macho-segment-name NODE_SEA

# Re-sign binary
codesign --sign - dist/app/node

Windows

# Generate blob
node --experimental-sea-config sea-config.json

# Copy node binary
copy $env:ProgramFiles\nodejs\node.exe .\dist\app\node.exe

# Inject blob
npx postject dist/app/node.exe NODE_SEA_BLOB dist/app/demo.blob ^
  --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2

Note: You can't just build once and run everywhere:

Code cache and snapshots are platform-specific

Native modules (still) require platform-specific compilation

Docker Integration

As someone who's built countless Docker images for Node.js apps, I couldn't wait to see how SEA could optimize container size.

I experimented with three different approaches:

Full Image (235MB)

Uses complete Node.js runtime
Includes OS dependencies
Simplest to build and debug

Minimal Image (156MB)
- Uses scratch as base
- Includes only essential OS dependencies
- Smallest possible footprint

That 156MB image size might not seem impressive compared to Go or Rust applications' Docker image, but it's a dramatic improvement over the typical 800MB+ Node.js image!

Full image

Uses full Node.js runtime - Contains development dependencies (OS)
Create dedicated user (always good)
Copy ESBuild bundle and change permissions
No need to install deps, dependencies are bundled
Run the app with node

FROM docker.io/node:lts-alpine

ENV HOST=0.0.0.0
ENV PORT=3000

WORKDIR /app

RUN addgroup --system node-sea-demo && \
  adduser --system -G node-sea-demo node-sea-demo

COPY dist/apps/node-sea-demo node-sea-demo/
RUN chown -R node-sea-demo:node-sea-demo .

CMD [ "node", "node-sea-demo" ]

Minimal image

alpine to start and dependencies to build
Install glibc for proper library copying
copy bundled code and SEA config
Bundle and remove debugging information ( # Strip the binary to remove debug symbols)
Uses scratch as a base image,
Eliminates unnecessary OS files
Include minimal OS dependencies (loader) and copy the Node.js SEA executable
Run the standalone executable

FROM node:lts-alpine AS build

WORKDIR /app

RUN apk add --no-cache build-base python3

RUN wget -q -O /etc/apk/keys/sgerrand.rsa.pub https://alpine-pkgs.sgerrand.com/sgerrand.rsa.pub && \
  wget https://github.com/sgerrand/alpine-pkg-glibc/releases/download/2.35-r1/glibc-2.35-r1.apk && \
  apk add --no-cache glibc-2.35-r1.apk && \
  rm glibc-2.35-r1.apk

COPY dist/apps/node-sea-demo dist/apps/node-sea-demo
COPY apps/node-sea-demo/sea-config.json .

# Create the SEA bundle and verify the file exists and is executable
RUN node --experimental-sea-config sea-config.json && \
  cp $(command -v node) dist/apps/node-sea-demo/node && \
  npx postject dist/apps/node-sea-demo/node NODE_SEA_BLOB dist/apps/node-sea-demo/node-sea-demo.blob --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 && \
  chmod +x dist/apps/node-sea-demo/node && \
  # # Strip the binary to remove debug symbols
  strip dist/apps/node-sea-demo/node

# Create directory structure for dependencies
RUN mkdir -p deps && \
  # Copy all required shared libraries
  ldd dist/apps/node-sea-demo/node | grep "=> /" | awk '{print $3}' | \
  xargs -I '{}' cp -L '{}' deps/ && \
  # Copy additional required files
  cp /lib/ld-linux-*.so.* deps/ && \
  # Create necessary symlinks
  mkdir -p deps/lib64 && \
  cp /lib/ld-linux-*.so.* deps/lib64/


FROM scratch

COPY --from=build /app/deps /lib/
# Ensure lib64 exists and has the loader
COPY --from=build /app/deps/lib64 /lib64/
# Copy the Node.js SEA executable
COPY --from=build /app/dist/apps/node-sea-demo/node /app/node

ENV HOST=0.0.0.0
ENV PORT=3000

EXPOSE ${PORT}
ENTRYPOINT [ "/app/node" ]

Performance Benchmarks

Using the useCodeCache option offers a dual benefit of better performance and slightly improved code protection.

// sea-config.json
{
  // ...
  "useCodeCache": true // Enable code caching
}

I ran some benchmarks to see how the application performs when:

regular Node.js (no SEA)
running with code cache enabled
running without code cache

Here's what I found:

The results surprised me:

Code cache improved startup time by ~7%
Blob size increased by only ~7% with code cache enabled
Cold starts showed significant variance (typical for any Node.js app)
Hot starts were consistently faster with code cache

How Code Cache Works

When JavaScript code is executed, V8 (Node.js's JavaScript engine) compiles it to bytecode before execution. This compilation takes time. Code cache stores this pre-compiled bytecode, allowing V8 to skip the compilation step on subsequent runs.

The performance improvement is most noticeable for:

Application startup time (as shown in our benchmarks)
Cold starts in serverless environments
Complex codebase with many dependencies

For most applications, I'd definitely recommend enabling code cache despite the slight size increase.

The Reality of Code Protection

One question that frequently comes up when discussing SEA is:

"Are our source code and proprietary algorithms safe inside the executable?"

While SEA bundles your code inside the Node.js binary, it's important to understand that this is not true obfuscation. Let me demonstrate why.

Extracting Code from SEA Executables

As said already, a SEA is a Node.js binary with your code injected as a resource section. With the right tools, extracting this section is relatively straightforward.

On macOS, extracting code from a SEA executable is a bit more involved than on Linux due to the Mach-O binary format. Here's a demo:

# 1. First, examine the Mach-O headers to locate the NODE_SEA segment
otool -l dist/apps/node-sea-demo/node | grep -A 20 NODE_SEA

# 2. Note the offset, size, and address of the NODE_SEA segment
# The output will show something like:
  segname NODE_SEA
   vmaddr 0x0000000104e20000
   vmsize 0x0000000000254000
  fileoff 81739776
 filesize 2432242
  maxprot 0x00000001
 initprot 0x00000001
   nsects 1
    flags 0x0
Section
  sectname __NODE_SEA_BLOB
   segname NODE_SEA
# ...

# 3. Extract the segment using dd, extract from the offset <fileoff> and size <filesize>
dd if=your-sea-app of=extracted.blob bs=1 skip=81739776 count=2432242

Examining the Extracted Content

Once extracted, the blob contains the bundled JavaScript code in a readable format. Let's see what it actually looks like:

# Look for readable strings
strings extracted.blob | less

# For function declarations
strings extracted.blob | grep -A 10 "function" | less

# Targeting assets
strings extracted.blob | grep -A 10 "assets" | less

Amazing, right?

As you can see, the original source code remains largely intact and readable. This is why relying solely on SEA for code protection is insufficient for truly sensitive intellectual property.

How can we protect our code?

For genuinely sensitive code, I recommend a multi-layered approach:

Use SEA with Bytenode for basic protection (be aware it was already reversed engineered)
Keep truly sensitive algorithms on a secure server accessed via API
Consider legal protections (contracts, terms of service)

Remember: no code shipped to a client's machine can ever be 100% protected against a determined adversary with sufficient resources and time.

Conclusion

Node.js Single Executable Applications have transformed how I deliver Node.js applications, offering:

Improved deployment reliability
Better security through bundling
Reduced environmental dependencies
Optimized resource usage

After years of dubious deployment strategy, I can now distribute my Node.js applications as single files that "just work" on the target system.

Want to try it yourself? Here are some next steps:

Experiment with the provided example application
Evaluate SEA for your specific use cases
Implement in your CI/CD pipeline
Join the Node.js SEA community and contribute!

If you have questions or want to share your SEA experiences, drop a comment below or reach out to me on Linkedin or GitHub.

Edouard MaleixFollow

I am a Senior Software Engineer, focusing on distributed systems, application security and developer productivity/creativity. Based in Vienna 🥐, Austria.

Dynamic NestJS Listeners: Discover the Power of Lazy Loading

Edouard Maleix — Sun, 13 Oct 2024 11:46:34 +0000

In this post, I will show you how to register HTTP routes and message consumers in NestJS applications dynamically.

This demonstration will start by uncovering some NestJS internals, particularly an undocumented feature: the DiscoveryModule 🧐.

By dynamic routes, I mean routes unknown at the time of development but defined at runtime, late in the boot process.

If reading bores you, skip the talk and jump directly to the repository.

Problem

The declarative approach is great but can also bring some limitations.
In the routing case, the decorators used to declare HTTP routes and microservices listeners (@Get, @Post, @EventPattern, @MessagePattern) require static values known during development time and cannot be late-bound.

Examples:

@Get('users') defines a static route that can only change by modifying the code.
@MessagePattern('user.created') is not adaptable to dynamic topic structures.

Use cases

Scenario	Business Impact	Description
Modular Plugin Architecture	Allow developers to create modular plugins that can be easily integrated into a core application without modifying the underlying code.	A web development platform allows users to install plugins that add new features, each with its own set of HTTP routes.
White Labeling for E-commerce Platforms	Enable e-commerce platforms to offer white-labeled application versions to different clients without modifying the underlying codebase.	A popular e-commerce platform allows its clients (e.g., online retailers) to create custom platform versions with unique routes and listeners.
Customizable Integration Layers	Allow customers to customize the integration layer of an application based on their specific business needs without requiring code changes.	A CRM system allows users to integrate it with various external services (e.g., email marketing platforms and sales tools).
Feature Flags for Enterprise Applications	Enable enterprise applications to easily toggle certain features on or off based on user roles or organizational policies.	A large enterprise application allows administrators to toggle specific features (e.g., access to advanced analytics tools) on or off for different departments.
Multi-Tenancy in SaaS Applications	Allow Software-as-a-Service (SaaS) applications to support multiple tenants with their custom routes and listeners.	A SaaS-based customer engagement platform allows clients to create custom application versions with unique routes and listeners.

NestJS scanning and registration lifecycle

Word to the wise: to declare dynamic routes and listeners, we must first understand how NestJS inspects modules and scans the metadata to register them.

For both HTTP routes and microservices listeners, NestJS will scan the metadata and register the routes and listeners during the initialization phase when NestApplication.init and NestMicroservice.init are called.

However, each of them has its own registration process and components:

HTTP routes

Microservices listeners

When calling NestApplication.listen and NestMicroservice.listen, the init methods will be called if they were not before.

We have the following options to register dynamic routes and listeners:

create custom explorers as providers that scan the metadata and replace the placeholders with actual values
create custom adapters for HTTP API by implementing the HttpServer interface
create custom transport strategies for microservices by extending Server

Option 1 is the most straightforward and will be the focus of this article.

Create a Proof of Concept

The demonstration is a simple NestJS application with a single HTTP route, a single message consumer, and the following requirements:

Enable lazy evaluation of routes or message patterns with custom decorators and metadata explorers
Support for both HTTP routes and message consumers
Use environment variables to define the route and message pattern prefixes
Replace the placeholders pattern before registering the routes and listeners (before NestJSApplication.init and app.connectMicroservice)

Seems like a good plan, but how can we set up the placeholders and replace them with actual values?

We could use the reflect-metadata library to store the metadata and then scan it manually to replace the placeholders with actual values, but there is a better way.

During my NestJS codebase review, I started following the MetadataScanner thread and noticed it was also used by the DiscoveryModule. This module provides a powerful tool for exploring and inspecting the providers, controllers, and modules in your NestJS application, and it turns out to be the perfect tool for our use case.

Funny enough, it has been in the NestJS core for several years but is not used internally. One could think it is part of the public API, but surprisingly, it is still undocumented. Do you also get this treasure hunt feeling? 🏴‍☠️

Since the approach is very similar for HTTP and microservices listeners, I only explain the registration process of HTTP routes. You can use the same approach to register the microservice listeners, as can be seen in this internal library.

The approch is based on the following steps:

Create a custom decorator
Create the metadata scanner
Declare the dynamic route
Import the custom explorers
Update ConfigService type and validator (optional)
Testing (optional, or not 😏)

1. Create a custom decorator

For the HTTP routes, the starting point is the custom decorator: CustomHttpMethod, which takes a method and a path as arguments:

The path is a template string (e.g. ,$HTTP_ROUTE_PREFIX/:id) containing placeholders that actual values will replace.
The method is one of the HTTP methods (e.g., GET, POST, etc).

This decorator is used above the controller methods to define the dynamic routes (e.g., @CustomHttpMethod({ method: 'GET', path: '$HTTP_ROUTE_PREFIX/:id' })).

import { DiscoveryService } from '@nestjs/core';
import type { Method } from 'axios';

export const CustomHttpMethod = DiscoveryService.createDecorator<{
  method: Method;
  path: string;
}>();

You can also find an example using only the Reflect API from reflect-metadata library, in the example repository.

2. Create the metadata scanner

Register the custom explorer

The scanner is exposed as a dynamic NestJS module—CustomHttpMethodModule—that can be imported into any module to enable dynamic HTTP routes.

Dynamic module enhances reusability and allows for configuration from the outside.

The module is configurable with:

a store: a map of keys (placeholders) and values (replacements).
a list of modules containing the controllers to scan for the custom decorators.

export interface ICustomHttpMethodModuleOptions {
  store: Map<string, string>;
  modules: Type<unknown>[];
}

The module can be created using the forRoot and forRootAsync methods, which return a DynamicModule object containing the module configuration.
The module will import the DiscoveryModule to enable the scanning of the controllers and methods.
It provides and exports the CustomHttpMethodExplorer service, which injects the DiscoveryService and MetadataScanner.

@Module({})
export class CustomHttpMethodModule {
  static forRoot(
    options: ICustomHttpMethodModuleOptions,
    isGlobal?: boolean
  ): DynamicModule {
    return {
      module: CustomHttpMethodModule,
      imports: [DiscoveryModule],
      providers: [
        { provide: CustomHttpMethodModuleOptions, useValue: options },
        CustomHttpMethodExplorer,
      ],
      exports: [CustomHttpMethodExplorer],
      global: isGlobal,
    };
  }

  static forRootAsync(
    options: CustomHttpMethodModuleAsyncOptions,
    isGlobal?: boolean
  ): DynamicModule {
    return {
      module: CustomHttpMethodModule,
      imports: options.imports
        ? [...options.imports, DiscoveryModule]
        : [DiscoveryModule],
      providers: [
        ...this.createAsyncProviders(options),
        CustomHttpMethodExplorer,
      ],
      exports: [CustomHttpMethodExplorer],
      global: isGlobal,
    };
  }

  private static createAsyncProviders(
    options: CustomHttpMethodModuleAsyncOptions
  ): Provider[] {
    if (options.useFactory) {
      return [
        {
          provide: CustomHttpMethodModuleOptions,
          useFactory: options.useFactory,
          inject: options.inject ?? [],
        },
      ];
    }
    throw new Error('Invalid CustomHttpMethodModuleAsyncOptions');
  }
}

Iterate over the controllers and methods

The CustomHttpMethodExplorer is a provider that will:

retrieve the controllers attached to the modules provided in the options
scan and iterate over each controller's methods
search for methods that use the CustomHttpMethod decorator
substitute the placeholders with actual values from the store
decorate the method with the NestJS HTTP method decorator (e.g., @Get, @Post, etc.)

One of the benefits of using the DiscoveryService is that it provides methods to explore the metadata of the controllers and methods [getProviders, getControllers, getAllMethodNames and getMetadataByDecorator], without having to use low-level APIs like Reflect.

Bonus: the discoveryService.getMetadataByDecorator infers the type of the metadata.

The CustomHttpMethodExplorer service is instantiated when the module is imported and will scan the controllers and methods to replace the placeholders with actual values. > Alternatively, you can manually trigger the exploration in the main.ts file.

@Injectable()
export class CustomHttpMethodExplorer {
  readonly logger = new Logger(CustomHttpMethodExplorer.name);
  private readonly methodsMap = new Map(
    Object.entries({
      GET: Get,
      POST: Post,
      PUT: Put,
      DELETE: Delete,
      PATCH: Patch,
      OPTIONS: Options,
      HEAD: Head,
    } as const)
  );

  constructor(
    @Inject(CustomHttpMethodModuleOptions)
    private readonly options: CustomHttpMethodModuleOptions,
    private readonly discoveryService: DiscoveryService,
    private readonly metadataScanner: MetadataScanner
  ) {
    this.process();
  }

  get store(): Map<string, string> {
    return this.options.store;
  }

  get modules(): Type<unknown>[] {
    return this.options.modules;
  }

  private substituteValues(input: string): string {
    return input.replace(
      /\$(\w+)/g,
      (match, p1) => this.store.get(p1) || match
    );
  }

  private getMethodDecorator(
    method: string
  ): (path: string | string[]) => MethodDecorator {
    return this.methodMap.get(method.ToUpperCase()) || Get;
  }

  process() {
    const instances = this.discoveryService.getControllers({
      include: this.modules,
    });
    for (const wrapper of instances) {
      const handlers = this.metadataScanner.getAllMethodNames(
        wrapper.metatype.prototype
      );
      this.logger.log(`${wrapper.name}:`);
      for (const handler of handlers) {
        const metadata = this.discoveryService.getMetadataByDecorator(
          CustomHttpMethod,
          wrapper,
          handler
        );
        if (!metadata) {
          continue;
        }
        const { method, path } = metadata;
        const fulfilledPath = this.substituteValues(path);
        const decorator = this.getMethodDecorator(method);
        decorator(fulfilledPath)(
          wrapper.metatype,
          handler,
          Object.getOwnPropertyDescriptor(
            wrapper.metatype.prototype,
            handler
          ) as PropertyDescriptor
        );
        this.logger.log(`Mapped {${method} ${fulfilledPath}} route`);
      }
    }
  }
}

If you like it more low level, you can also find an example using only Reflect API, in the example repository

3. Declare the dynamic route

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @CustomHttpMethod({ method: 'GET', path: '$HTTP_METHOD_PREFIX/:id' })
  getData(@Param('id') id: string) {
    return this.appService.getData(id);
  }

  //...
}

4. Import the custom explorers

In app.module.ts, add the custom explorers to the imports array.

@Module({
  imports: [
    // ...
    CustomHttpMethodModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (
        configService: ConfigService<EnvironmentVariables, true>
      ) => {
        const store = new Map<string, string>();
        store.set(
          'HTTP_METHOD_PREFIX',
          configService.get('HTTP_METHOD_PREFIX')
        );
        return { store, modules: [AppModule] };
      },
    }),
    // ...
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

5. Update ConfigService type and validator

To provide a better developer experience, we can use the class-transformer and class-validator libraries to validate the configuration object and provide default values (any other validation library will do).

import { Expose } from 'class-transformer';
import { IsInt, IsPositive, IsString, IsUrl, Min } from 'class-validator';

export class EnvironmentVariables {
  //...
  @Expose()
  @IsString()
  HTTP_METHOD_PREFIX = 'http-demo-1';

  //...
}

The ConfigModule is updated to use the plainToInstance function from class-transformer to transform the configuration object into an instance of the EnvironmentVariables class.
The validateSync function from class-validator validates the instance of the EnvironmentVariables class.
After this validation we can increase the ConfigService type safety by including the EnvironmentVariables class (e.g., ConfigService<EnvironmentVariables, true>).

@Module({
  imports: [
    ConfigModule.forRoot({
      cache: true,
      isGlobal: true,
      validate: (config) => {
        const validatedConfig = plainToInstance(EnvironmentVariables, config, {
          excludeExtraneousValues: true,
          exposeDefaultValues: true,
        });
        const errors = validateSync(validatedConfig, {
          skipMissingProperties: false,
        });
        if (errors.length > 0) {
          throw new Error(errors.toString());
        }
        return validatedConfig;
      },
    }),
    //...
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

6. Testing

The workspace includes E2E tests that will send:

HTTP request to the dynamic route
MQTT message to the dynamic listener

Feel free to run the tests to see the demonstration in action.

docker compose up -d
npx nx run demo-1:serve
# in another terminal
nx run demo-1-e2e:e2e

Going further

With this knowledge, you can implement the following scenarios:

Replace the template string with a printf-like syntax
Fetch routes and listeners from a remote service or a database
Build your explorer modules to create a plugin system
Create a reusable generic controller to avoid repeating decorators
Create groups of controllers/providers
Attach decorators to all controllers

Conclusion

I hope you enjoyed this demonstration and learned something new about NestJS internals.

If you want to show your appreciation, you can find the code in this repository and give it a star ⭐️.

Edouard MaleixFollow

I am a Senior Software Engineer, focusing on distributed systems, application security and developer productivity/creativity. Based in Vienna 🥐, Austria.