Registry / auth-security / decentraland-crypto-middleware

decentraland-crypto-middleware

library1.3.0jsnpmunverified

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.

auth-security web-framework http-networking crm-productivity

npm install decentraland-crypto-middleware

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DECENTRALAND-CRYPT

decentraland-crypto-middleware

auth-securityjavascriptv1.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DecentralandSignatureData

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

✗ import DecentralandSignatureData from 'decentraland-crypto-middleware'

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

express

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

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

Function returning Express middleware. Import individually or via namespace.

koa

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

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

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

passport

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

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

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

wellKnownComponents

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

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

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

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'));

Debug

Known issues

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

fix

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

affects: >=1.0.0

deprecatedThe `verifyExpiration` option was removed in v1.0.4; expiration is now always verified.

fix

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

affects: >=1.0.4

gotchaPassport strategy name must be 'decentraland'. Using a different name will fail.

fix

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

affects: >=1.0.0

breakingv1.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.

affects: >=1.3.0

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

fix

Check for `authMetadata` existence before accessing its properties.

affects: >=1.0.0

Errors

Common errors & fixes

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

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: Invalid signature

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: Signature expired

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).

TypeError: req.auth is not a function

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

fix

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

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

@decentraland/cryptorequiredCore library for signature verification and auth chain parsing.

Agent activity

48 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/decentraland/decentraland-crypto-middleware ↗

packagehttps://www.npmjs.com/package/decentraland-crypto-middleware ↗

homepagehttps://decentraland.org ↗