unwrap

Paste any token or encoded string: Unwrap detects what it is (JWT, base64, hex, gzip, URL-encoded, Basic Auth, hashes…) and decodes it. Also verifies and signs JWTs, encodes, hashes/HMACs and encrypts with AES-256-GCM

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.3.0
Author: abraao_o_h

Documentation

n8n-nodes-unwrap

Paste any token or encoded string. Unwrap finds out what it is, decodes it layer by layer, and verifies JWT signatures. It also goes the other way: signs JWTs, encodes, hashes (and HMACs) and encrypts.

Operation What it does
Decode Detects the format and decodes it
Verify JWT Checks signature and dates
Sign JWT Creates a signed JWT
Encode Base64, hex, URL, gzip/deflate, Basic Auth
Hash SHA, MD5 or HMAC, with constant-time compare
Encrypt / Decrypt AES-256-GCM with your key, on a value or on some fields
Verify Webhook GitHub, Stripe, Slack, Shopify and Standard Webhooks signatures
Generate UUID, random secret / AES key, password, TOTP (2FA) code
"Bearer eyJhbGciOiJSUzI1NiIs…"   →  { type: "jwt", header, payload, expiresAt, expired: false, verified: false }
"H4sIAAAAAAAA%2F6tWSlSyMjQ…"      →  { type: "json", value: {…}, layers: ["url", "base64", "gzip"] }
"Basic YW5hOnMzY3IzdA=="          →  { type: "basic", username: "ana", password: "s3cr3t" }
"5e884898da28047151d0e56f8dc…"    →  { type: "hash", algorithms: ["SHA-256", …] }

Install

In n8n, go to Settings → Community Nodes → Install and enter n8n-nodes-unwrap.

Decode

Detects the format and peels every layer it finds: URL-encoding, base64/base64url, hex, gzip, zlib and raw deflate. It stops at something it recognizes, at plain text, or after Max Layers (5).

Type What you get
jwt header, payload, issuedAt, notBefore, expiresAt, expired, expiresInSeconds, verified: false
jwe header only: the payload is encrypted
paseto public: the payload (not verified). local: encrypted
fernet issuedAt only: the payload is encrypted
basic username, password (needs the Basic prefix)
json, saml, xml, text the decoded value
hash the likely algorithms (bcrypt, Argon2, MD5, SHA-1, SHA-256…). Hashes cannot be decoded
uuid version
binary the bytes, when you force a format and the result is not text
unknown not a known format. Often an opaque access token: only the server that issued it can read it

layers always lists what was peeled, in order.

Detection is a guess. A short value can be valid hex and valid base64 at the same time. Unwrap only accepts a layer when the result makes sense (readable text or compressed data), but if it guesses wrong, set Format to the one you know.

[!WARNING]
Decode does not check signatures. Anyone can create a JWT with any content. Before trusting a token to grant access, use Verify JWT.

Verify JWT

Checks the signature and the dates. The result has valid: true, or valid: false with a reason you can test in an IF:

reason Meaning
invalid_signature the signature does not match the key
expired / not_yet_valid outside exp / nbf (see Clock Tolerance)
issuer_mismatch / audience_mismatch iss / aud not in the accepted list
alg_not_allowed the token's algorithm is not allowed for this key
key_mismatch the key is of the wrong kind for the algorithm
no_matching_key no JWKS key has the token's kid
malformed not a signed JWT

With If Invalid → Stop With an Error, an invalid token stops the workflow instead.

Keys:

  • Credential: the JWT Auth credential that comes with n8n (the same one the native JWT node uses). Passphrase for HS256/384/512, PEM Key for RS, PS, ES and EdDSA: a public key, a certificate, or a private key (only its public half is used).
  • JWKS URL: the public keys published by the issuer, for example https://your-tenant.auth0.com/.well-known/jwks.json. An OpenID configuration URL (…/.well-known/openid-configuration) works too. Keys are cached for 10 minutes. When a token has a kid that is not in the cache, the JWKS is fetched again (at most every 30 seconds), so key rotation works.

Safe defaults:

  • A passphrase only checks HS256/384/512 and a public key only checks public key algorithms. This blocks the attack where a token is signed with HS256 using the public key as the secret.
  • alg: none is never accepted.
  • Narrow it further with Allowed Algorithms, and check Issuer and Audience whenever you know them.

Sign JWT

Write the claims in Payload and pick the JWT Auth credential: a passphrase signs HS256/384/512, a PEM private key signs RS, PS, ES or EdDSA. The algorithm comes from the credential unless you set Algorithm in the options.

iat is set to now and exp to now + Expires In (3600 seconds by default, 0 for no expiration), unless the payload already has them. Issuer, Audience and Key ID set iss, aud and the kid header.

Output: token, header, payload, expiresAt.

Encode

The reverse of Decode: Base64, Base64url, Hex, URL-encoded, Gzip + Base64, Deflate (zlib) + Base64, raw Deflate + Base64 (SAML redirect), and a Basic Auth header (Value is the username). An object becomes JSON first.

Hash

MD5, SHA-1, SHA-256/384/512 and SHA3-256/512, in hex, base64 or base64url. Turn on HMAC to sign with the Unwrap Secret credential.

Compare With checks a given hash in constant time and adds matches: true/false. It ignores case for hex and a sha256= style prefix, so it checks webhook signatures directly:

Webhook (Raw Body) → Unwrap: Hash, SHA-256, HMAC on, Value {{ $json.body }},
                     Compare With {{ $json.headers["x-hub-signature-256"] }} → IF matches

Hash the exact body the sender signed: a body parsed and turned back into JSON can differ (spaces, key order).

Bcrypt and Argon2 are not included: they would need an extra library. Decode still recognizes them.

Encrypt / Decrypt

AES-256-GCM with the Unwrap Secret credential. Only who has the key can read the result, and any change to it makes Decrypt fail. Decrypt gives back JSON as an object.

The credential's Secret Format:

  • Passphrase: any text. Each message gets a random salt and the key comes from scrypt (N=16384, r=8, p=1). About 50 ms per item.
  • Hex / Base64: a raw 32-byte key, fast. Generate one with openssl rand -hex 32.

The output is base64 of [salt (16 bytes, passphrase only)] + IV (12) + auth tag (16) + ciphertext, so other systems can decrypt it too.

Target → Fields of the Item encrypts only some fields, in place, and keeps the rest readable (useful for personal data such as CPF or card numbers):

Fields: cpf, card.number
{ name: "Ana", cpf: "123.456.789-00", card: { number: 4111, brand: "visa" } }
→ { name: "Ana", cpf: "pX3k…", card: { number: "9fQa…", brand: "visa" } }

Decrypt with the same fields gives the original item back, with numbers, objects and lists as they were. Missing fields are skipped.

[!WARNING]
Losing the secret means losing the data. Changing the Secret Format makes old values unreadable.

Verify Webhook

Checks a webhook signature exactly as each provider documents it, with the secret in the Unwrap Secret credential:

Provider Headers Notes
GitHub X-Hub-Signature-256
Shopify X-Shopify-Hmac-Sha256
Slack X-Slack-Signature, X-Slack-Request-Timestamp the Signing Secret
Stripe Stripe-Signature the whsec_… endpoint secret, as is
Standard Webhooks webhook-* or svix-* Svix, Clerk, Resend…: the whsec_… secret, as is

In the Webhook node, turn on Raw Body: the signature is over the exact bytes that arrived, and Unwrap reads them from the data binary. Headers defaults to {{ $json.headers }}.

For Stripe, Slack and Standard Webhooks, Max Age (300 s) rejects old webhooks, so a captured request cannot be sent again. The result is valid: true (with the timestamp), or valid: false with a reason: invalid_signature, missing_header or too_old.

Generate

  • UUID (v4)
  • Random Secret / AES Key: random bytes in hex, base64 or base64url. 32 bytes in hex is a key for the Unwrap Secret (Secret Format: Hex).
  • Password: lower and upper case, digits and (optionally) symbols, at least one of each, without look-alikes (0/O, 1/l/I).
  • TOTP Code (2FA): the current code of an authenticator app, from n8n's TOTP credential (the base32 secret the service shows when you set up 2FA). Output: code and secondsLeft.

Explain With AI

Turn on Explain With AI in Decode or Verify JWT and a Chat Model input appears under the node. Connect any model (OpenAI, Anthropic, Gemini, Ollama…) and each result gets an explanation:

Access token from Acme's Auth0 (iss https://acme.auth0.com/) for user 42, with the scope read:invoices. It expires in 12 minutes. It was only decoded, not verified: use Verify JWT with https://acme.auth0.com/.well-known/jwks.json before trusting it.

When the format is unknown, the model suggests what it probably is; when Verify fails, it explains the reason and how to fix it.

What the AI can and cannot do:

  • It only explains. Decoding, signatures, dates and valid are computed by code, and the explanation is a separate field: a model that says "valid" changes nothing.
  • Signatures, raw tokens, Basic Auth passwords and secrets are never sent. For unknown values only the shape goes (length, kinds of characters, the first characters).
  • Mask Personal Data (on by default) hides emails, long numbers (CPF, phone, card) and fields like name, email, cpf, address, password before sending. Turn it off only with a model you trust, such as a local one.
  • If the model fails (rate limit, timeout), the item keeps its result and gets explanationError instead.
  • One model call per item: with many items, it costs time and tokens.

Options: Explanation Language (default English) and Extra Instructions for AI.

AI Agent tool

Unwrap can be connected as a tool of the AI Agent node, so the agent can decode or verify a token when it needs to.

For a self-hosted n8n, community nodes can be used as tools only with this environment variable:

N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

Tokens are sensitive: what the tool returns goes to the language model. Prefer Verify JWT results, and avoid sending live tokens to an external model if that matters for you.

Build

npm install
npm run build
npm test
npm run lint

Discussion