WebCrypto-based Iron Implementation

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax with an ESM-only package.
  fix Change `const Iron = require('iron-webcrypto')` to `import * as Iron from 'iron-webcrypto'` and ensure your project is configured for ESM.

• TypeError: crypto.subtle is undefined

  cause Running `iron-webcrypto` in an environment that lacks the WebCrypto API, most commonly an older Node.js version (<v20).
  fix Upgrade your Node.js version to v20 or higher. Alternatively, ensure your environment provides a `crypto.subtle` implementation.

• RangeError: Password must be at least 32 characters long.

  cause The provided password for `seal` or `unseal` is shorter than the minimum required length (default 32 characters).
  fix Provide a password that meets or exceeds the minimum length configured in `SealOptions.encryption.minPasswordlength` (default: 32 characters). Always use strong, securely generated passwords.

Warnings

• breaking Version 2.0.0 of `iron-webcrypto` drops support for Node.js versions older than v20. Running on unsupported versions may lead to runtime errors or unexpected behavior due to missing WebCrypto APIs.
  Fix: Upgrade your Node.js environment to version 20 or higher to ensure compatibility.
• breaking Internal utility functions for base64/buffer operations, which were not part of the public API, have been removed in v2.0.0. If you were using these, migrate to dedicated libraries like `uint8array-extras`.
  Fix: Replace usage of internal utility functions with purpose-built libraries like `uint8array-extras` for base64/buffer operations.
• gotcha While `iron-webcrypto` technically functions in a browser environment due to its WebCrypto reliance, it is not recommended for client-side use. Exposing encryption secrets (passwords) to the client poses significant security risks.
  Fix: Use `iron-webcrypto` primarily in server-side, worker, or other secure backend environments where encryption secrets can be properly managed and protected.
• gotcha Encryption secrets (passwords) should never be hardcoded in application code. They must be stored securely, ideally in environment variables, a secrets manager, or a secure configuration system.
  Fix: Refactor your application to load encryption secrets from environment variables (e.g., `process.env.IRON_SECRET_KEY`) or a secure secrets management service.
• gotcha The default `minPasswordLength` is 32 characters. Using passwords shorter than this may be insecure and could result in runtime errors or weakened cryptography.
  Fix: Ensure that the password provided for sealing and unsealing is at least 32 characters long. Adjust `minPasswordLength` in `SealOptions` if absolutely necessary for specific use cases (though not recommended).

Install

• npm install iron-webcrypto npm
• yarn add iron-webcrypto yarn
• pnpm add iron-webcrypto pnpm

Imports

• Iron
  wrong:

  const Iron = require('iron-webcrypto')

  correct:

  import * as Iron from 'iron-webcrypto'

  iron-webcrypto is an ESM-only package since v2; CommonJS `require` is not supported. For Deno/JSR, use `import * as Iron from '@brc-dd/iron'`.
• seal, unseal
  wrong:

  import { seal } from 'iron-webcrypto/lib/seal'

  correct:

  import { seal, unseal } from 'iron-webcrypto'

  All primary functions are named exports from the top-level package. Avoid importing from internal paths.
• defaults

  import { defaults } from 'iron-webcrypto'

  Commonly used default options for sealing and unsealing.

Quickstart

Demonstrates sealing a JSON object into a tamper-evident, encrypted token and then unsealing it, highlighting the use of a secure password and default options.

import * as Iron from 'iron-webcrypto'

async function runCryptoExample() {
  // It's crucial to use a strong, randomly generated secret stored securely
  // in environment variables or a secrets manager. NEVER hardcode in production.
  const password = process.env.IRON_SECRET_KEY ?? 'a_long_random_secret_please_change_me_32_chars_min'
  
  if (password.length < 32) {
    console.error('Warning: Password must be at least 32 characters long for security.')
    return
  }

  const payload = { userId: 123, scope: ['user'], issuedAt: Date.now() }

  try {
    const sealed = await Iron.seal(payload, password, Iron.defaults)
    console.log('Sealed token:', sealed)

    // Simulate receiving the token later or in another service
    const unsealed = await Iron.unseal(sealed, password, Iron.defaults)
    console.log('Unsealed payload:', unsealed)

    // Example with TTL (Time To Live)
    const optionsWithTTL = { ...Iron.defaults, ttl: 5000 } // 5 seconds expiry
    const sealedWithTTL = await Iron.seal(payload, password, optionsWithTTL)
    console.log('Sealed token with TTL:', sealedWithTTL)

    // Wait for expiry (optional, for demonstration)
    // await new Promise(resolve => setTimeout(resolve, 6000))
    // try {
    //   await Iron.unseal(sealedWithTTL, password, optionsWithTTL)
    // } catch (e) {
    //   console.log('Expected expiry error:', e.message)
    // }

  } catch (error) {
    console.error('Cryptography operation failed:', error)
  }
}

runCryptoExample()