@oreefy/jwe

A lightweight Web Crypto library to encrypt and decrypt plaintext via AES-256-GCM within the Oreefy ecosystem. Note: This is a custom utility and not a strict RFC 7516 JWE implementation.

@oreefy/jwe is a library built for the Oreefy ecosystem. The package is officially developed, maintained, and fully controlled by Oreefy, ensuring long-term stability, consistency, and compatibility across the ecosystem.

Required Capabilities

• JavaScript / TypeScript
• Web Crypto API (crypto)

API Reference

import { jwe } from "@oreefy/jwe";

jwe.encrypt();
jwe.decrypt();
jwe.isCiphertext();
jwe.generateEncryptionSecret();

jwe.encrypt()

Encrypt plaintext using AES-256-GCM and returns a custom ciphertext string.

import { jwe } from "@oreefy/jwe";

// Supported expiration units
type Unit = "s" | "m" | "h" | "d" | "mo" | "y";

interface Options {
  secret: string; // A 64-character hexadecimal secret representing a 256-bit AES key.
  plaintext: string; // The plaintext value to encrypt.
  issuer?: string; // Optional issuer value authenticated as AES-GCM AAD.
  audience?: string; // Optional audience value authenticated as AES-GCM AAD.
  subject?: string; // Optional subject value authenticated as AES-GCM AAD.
  expiresIn?: `${number}${Unit}` | number; // Optional expiration duration. A string uses a duration unit; a number represents seconds. The undefined is lifetime.
}

const ciphertext = jwe.encrypt(options): Promise<string>;

jwe.decrypt()

Decrypt and authenticate a ciphertext generated by jwe.encrypt().

import { jwe } from "@oreefy/jwe";

interface Options {
  secret: string; // The same 64-character hexadecimal secret used for encryption.
  ciphertext: string; // Ciphertext generated by "jwe.encrypt()".
  issuer?: string; // Must match the issuer used during encryption.
  audience?: string; // Must match the audience used during encryption.
  subject?: string; // Must match the subject used during encryption.
}

const plaintext = jwe.decrypt(options): Promise<string | null>;

The issuer, audience, and subject values are authenticated using AES-GCM Additional Authenticated Data (AAD). If any authenticated value differs from the values used during encryption, decryption fails.

jwe.isCiphertext()

Checks whether a value matches the ciphertext format generated by this library.

import { jwe } from "@oreefy/jwe";

interface Options {
  ciphertext?: string | null;
}

const isValid = jwe.isCiphertext(options): boolean;

jwe.isCiphertext() validates the ciphertext format only. It does not verify the encryption key, authenticity, integrity, or expiration. Use jwe.decrypt() for actual cryptographic verification.

jwe.generateEncryptionSecret()

Generates a cryptographically secure 256-bit encryption secret.

import { jwe } from "@oreefy/jwe";

// Returns a 64-character hexadecimal string representing 32 random bytes.
// E.G. 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
const secret = jwe.generateEncryptionSecret(): string;

For production applications, encryption secrets should be stored securely using environment variables or a dedicated secret-management system.

Do not hard-code encryption secrets in source code.

Expiration (Optional)

When expiresIn is not set or is undefined, the ciphertext does not expire and remains valid indefinitely.

And when expiresIn is provided during encryption, the expiration timestamp is stored inside the authenticated encrypted payload.

Examples:

• String uses a duration Unit
  • expiresIn: "30s"
  • expiresIn: "15m"
  • expiresIn: "2h"
  • expiresIn: "7d"
  • expiresIn: "1mo"
  • expiresIn: "1y"
• A numeric value represents seconds:
  • expiresIn: 3600 (which represents one hour.)

After expiration, jwe.decrypt() returns: null.

Ciphertext Format

The library uses a custom ciphertext format: <iv>.<encrypted-data>. Both components are encoded as hexadecimal strings. The IV is always 12 bytes (24 hexadecimal characters), while the encrypted data contains the AES-GCM ciphertext and authentication tag.

Example: a1b2c3d4e5f60718293a4b5c.8f2a... This format is specific to @oreefy/jwe and is not an RFC 7516 JWE compact serialization format.

About Oreefy

Oreefy is an affordable business ecosystem designed for small to enterprise businesses. Oreefy provides essential software you need for your modern business within a single ecosystem. It will save you significant time, effort, and money.

License

MIT © Oreefy