Decentraland Authentication Middleware

1.3.0 verified Sat Apr 25 auth: no javascript

Multi-framework middleware (Express, Koa, PassportJS, Well-Known Components) for authenticating HTTP requests signed with @decentraland/SignedFetch. Current stable version is 1.3.0 (June 2024), with minor releases every 6–12 months. Key differentiator: unified auth verification across Node.js web frameworks using Ethereum signature-based identity, suitable for Decentraland dApps. Supports optional verification, configurable expiration, and metadata content verification. Depends on @decentraland/crypto for signature logic.

Common errors

error TypeError: Cannot read properties of undefined (reading 'auth') ↓

cause Middleware not applied or optional mode when signature is missing.

fix

Ensure the middleware is added to the route and if using optional: true, check req.auth for undefined.

error Error: Invalid signature ↓

cause The request's authentication header contains an invalid or tampered signature.

fix

Verify that the client uses @decentraland/SignedFetch correctly and that the signing identity matches the expected address.

error Error: Signature expired ↓

cause The timestamp in the signature exceeds the expiration threshold (default 10 minutes).

fix

Re-sign the request with a fresh timestamp or increase the expiration option (though removed in later versions, check version).

error TypeError: req.auth is not a function ↓

cause Treating `auth` as a function instead of a string property.

fix

Use req.auth directly as a string, not req.auth().

Warnings

gotcha Type augmentation requires manual type intersection. `req.auth` is not typed unless you cast or use `DecentralandSignatureData`. ↓

fix Use `req: Request & DecentralandSignatureData` for correct typing.

deprecated The `verifyExpiration` option was removed in v1.0.4; expiration is now always verified. ↓

fix Remove any `expiration` option passed to middleware – it is ignored.

gotcha Passport strategy name must be 'decentraland'. Using a different name will fail. ↓

fix Use `passport.authenticate('decentraland')` exactly.

breaking v1.3.0 added `verifyMetadataContent` option; if you pass metadata that includes content, it will now be verified by default unless opted out. ↓

fix Set `verifyMetadataContent: false` in options if you don't want metadata content verification.

gotcha The `authMetadata` property may be `undefined` when `optional: true` and no signature is present. ↓

fix Check for `authMetadata` existence before accessing its properties.

Install

npm install decentraland-crypto-middleware

yarn add decentraland-crypto-middleware

pnpm add decentraland-crypto-middleware

Imports

DecentralandSignatureData

wrong

import DecentralandSignatureData from 'decentraland-crypto-middleware'

correct

import { DecentralandSignatureData } from 'decentraland-crypto-middleware'

Named export (not default). Augments request/context types with auth and authMetadata.

express

wrong

import * as dcl from 'decentraland-crypto-middleware'; dcl.express(); // correct usage but wrong import style for the function

correct

import { express } from 'decentraland-crypto-middleware'

Function returning Express middleware. Import individually or via namespace.

koa

wrong

import { koaMiddleware } from 'decentraland-crypto-middleware'

correct

import { koa } from 'decentraland-crypto-middleware'

Exported as `koa`, not `koaMiddleware`. Named export.

passport

wrong

import { passportStrategy } from 'decentraland-crypto-middleware'

correct

import { passport } from 'decentraland-crypto-middleware'

Exported as `passport`, returns a Passport strategy constructor. Named export.

wellKnownComponents

wrong

import { wkc } from 'decentraland-crypto-middleware'

correct

import { wellKnownComponents } from 'decentraland-crypto-middleware'

Exported as `wellKnownComponents`, not abbreviated. Named export.

Quickstart

Sets up an Express route protected by Decentraland signature verification using the express() middleware.

import { express } from 'decentraland-crypto-middleware';
import expressApp from 'express';

const app = expressApp();

app.get('/protected',
  express(),
  (req, res) => {
    const address = (req as any).auth;
    res.json({ address });
  }
);

app.listen(3000, () => console.log('Server running on port 3000'));