jose 6.2.5: flattenedDecrypt

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify flattenedDecrypt in pkg:npm/jose@6.2.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/jose@6.2.5
Demonstrate these symbols/APIs:
  - flattenedDecrypt

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:55d9795ad079f3d1a467f74413cdeb79279649af0e59746fee63fd08a7f64492","contract":["flattenedDecrypt decrypts a Flattened JWE object using a direct symmetric key and returns plaintext bytes and protectedHeader","flattenedDecrypt extracts sharedUnprotectedHeader and unprotectedHeader from Flattened JWE objects","flattenedDecrypt verifies and returns Additional Authenticated Data (AAD) present in Flattened JWE","flattenedDecrypt supports asymmetric key decryption using ECDH-ES key agreement","flattenedDecrypt accepts a key resolver callback function for dynamic key selection","flattenedDecrypt enforces keyManagementAlgorithms and contentEncryptionAlgorithms options restrictions","flattenedDecrypt rejects decryption when ciphertext, tag, or protected header is tampered with"],"goal":"verify flattenedDecrypt in pkg:npm/jose@6.2.5","kind":"HOW","packages":["pkg:npm/jose@6.2.5"],"schemaVersion":1,"symbols":["flattenedDecrypt"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/jose@6.2.5"],"schemaVersion":1,"subject":"pkg:npm/jose@6.2.5","symbols":["flattenedDecrypt"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-jose-flattened-decrypt",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-jose-flattened-decrypt",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "jose": "6.2.5"
      }
    },
    "node_modules/jose": {
      "version": "6.2.5",
      "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.5.tgz",
      "integrity": "sha512-2E5L2yRp03FnwreJLJX8/r7mHiZICCf8kG7fAsTWkSQTDAcc46NIZoQLKy+EJ8sPoJlxyS4OQR5H70LjIZZlIQ==",
      "license": "MIT",
      "funding": {
        "url": "https://github.com/sponsors/panva"
      }
    }
  }
}

{
  "name": "sample-jose-flattened-decrypt",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "main": "src/index.js",
  "dependencies": {
    "jose": "6.2.5"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify flattenedDecrypt in pkg:npm/jose@6.2.5",
  "kind": "HOW",
  "packages": [
    "pkg:npm/jose@6.2.5"
  ],
  "symbols": [
    "flattenedDecrypt"
  ]
}

import {
  flattenedDecrypt,
  FlattenedEncrypt,
  generateSecret,
  generateKeyPair
} from 'jose';

const encoder = new TextEncoder();
const decoder = new TextDecoder();

/**
 * Decrypts a Flattened JWE object into plaintext and metadata.
 *
 * @param {import('jose').FlattenedJWE} jwe - Flattened JWE object to decrypt.
 * @param {Uint8Array|CryptoKey|import('jose').FlattenedDecryptGetKey} key - Key or key resolver callback.
 * @param {import('jose').FlattenedDecryptOptions} [options] - Decryption options (e.g. keyManagementAlgorithms).
 * @returns {Promise<{ plaintext: string, plaintextBytes: Uint8Array, protectedHeader?: object, unprotectedHeader?: object, sharedUnprotectedHeader?: object, additionalAuthenticatedData?: Uint8Array }>}
 */
export async function decryptFlattened(jwe, key, options) {
  const result = await flattenedDecrypt(jwe, key, options);
  return {
    plaintext: decoder.decode(result.plaintext),
    plaintextBytes: result.plaintext,
    protectedHeader: result.protectedHeader,
    unprotectedHeader: result.unprotectedHeader,
    sharedUnprotectedHeader: result.sharedUnprotectedHeader,
    additionalAuthenticatedData: result.additionalAuthenticatedData
  };
}

/**
 * Encrypts a payload into a Flattened JWE object for testing and demonstration.
 *
 * @param {string|Uint8Array} plaintext - Plaintext payload to encrypt.
 * @param {Uint8Array|CryptoKey} key - Encryption key.
 * @param {object} [protectedHeader] - Protected JWE header parameters.
 * @param {object} [options] - Optional additional headers and parameters.
 * @returns {Promise<import('jose').FlattenedJWE>}
 */
export async function encryptFlattened(plaintext, key, protectedHeader = { alg: 'dir', enc: 'A256GCM' }, options = {}) {
  const bytes = typeof plaintext === 'string' ? encoder.encode(plaintext) : plaintext;
  const encrypter = new FlattenedEncrypt(bytes);

  if (protectedHeader) {
    encrypter.setProtectedHeader(protectedHeader);
  }
  if (options.unprotectedHeader) {
    encrypter.setUnprotectedHeader(options.unprotectedHeader);
  }
  if (options.sharedUnprotectedHeader) {
    encrypter.setSharedUnprotectedHeader(options.sharedUnprotectedHeader);
  }
  if (options.additionalAuthenticatedData) {
    const aad = typeof options.additionalAuthenticatedData === 'string'
      ? encoder.encode(options.additionalAuthenticatedData)
      : options.additionalAuthenticatedData;
    encrypter.setAdditionalAuthenticatedData(aad);
  }
  if (options.keyManagementParameters) {
    encrypter.setKeyManagementParameters(options.keyManagementParameters);
  }
  if (options.contentEncryptionKey) {
    encrypter.setContentEncryptionKey(options.contentEncryptionKey);
  }
  if (options.initializationVector) {
    encrypter.setInitializationVector(options.initializationVector);
  }

  return await encrypter.encrypt(key);
}

export {
  flattenedDecrypt,
  FlattenedEncrypt,
  generateSecret,
  generateKeyPair
};

import assert from 'node:assert/strict';
import {
  flattenedDecrypt,
  FlattenedEncrypt,
  generateSecret,
  generateKeyPair,
  decryptFlattened,
  encryptFlattened
} from '../src/index.js';
import * as jose from 'jose';

const encoder = new TextEncoder();
const decoder = new TextDecoder();

// 1. Verify module exports
assert.equal(typeof flattenedDecrypt, 'function', 'flattenedDecrypt must be a function');
assert.strictEqual(flattenedDecrypt, jose.flattenedDecrypt, 'flattenedDecrypt must match jose export');
assert.equal(typeof FlattenedEncrypt, 'function', 'FlattenedEncrypt must be a function');
assert.strictEqual(FlattenedEncrypt, jose.FlattenedEncrypt, 'FlattenedEncrypt must match jose export');

// 2. Direct symmetric decryption: decrypts a Flattened JWE object using a direct symmetric key and returns plaintext bytes and protectedHeader
const secretKey = await generateSecret('A256GCM');
const payloadText = 'Confidential payload data for flattenedDecrypt contract';
const plaintextBytes = encoder.encode(payloadText);

const encrypter = new FlattenedEncrypt(plaintextBytes);
encrypter.setProtectedHeader({ alg: 'dir', enc: 'A256GCM' });
const jwe = await encrypter.encrypt(secretKey);

assert.equal(typeof jwe, 'object', 'JWE must be an object');
assert.equal(typeof jwe.ciphertext, 'string', 'ciphertext must be a string');
assert.equal(typeof jwe.iv, 'string', 'iv must be a string');
assert.equal(typeof jwe.tag, 'string', 'tag must be a string');
assert.equal(typeof jwe.protected, 'string', 'protected must be a string');

const decryptResult = await flattenedDecrypt(jwe, secretKey);
assert.ok(decryptResult.plaintext instanceof Uint8Array, 'plaintext must be a Uint8Array');
assert.equal(decoder.decode(decryptResult.plaintext), payloadText, 'Decrypted text must match original payload');
assert.deepEqual(decryptResult.protectedHeader, { alg: 'dir', enc: 'A256GCM' }, 'Protected header must match');

const helperResult = await decryptFlattened(jwe, secretKey);
assert.equal(helperResult.plaintext, payloadText, 'Helper decrypted text must match original payload');
assert.deepEqual(helperResult.plaintextBytes, plaintextBytes, 'Helper plaintext bytes must match');
assert.deepEqual(helperResult.protectedHeader, { alg: 'dir', enc: 'A256GCM' });

// 3. Header handling: extracts sharedUnprotectedHeader and unprotectedHeader from Flattened JWE objects
const sharedHeader = { kid: 'shared-key-1' };
const recipientHeader = { cty: 'application/json' };

const encWithHeaders = new FlattenedEncrypt(plaintextBytes);
encWithHeaders.setProtectedHeader({ alg: 'dir', enc: 'A256GCM' });
encWithHeaders.setSharedUnprotectedHeader(sharedHeader);
encWithHeaders.setUnprotectedHeader(recipientHeader);
const jweWithHeaders = await encWithHeaders.encrypt(secretKey);

const decryptWithHeadersResult = await flattenedDecrypt(jweWithHeaders, secretKey);
assert.equal(decoder.decode(decryptWithHeadersResult.plaintext), payloadText);
assert.deepEqual(decryptWithHeadersResult.sharedUnprotectedHeader, sharedHeader, 'sharedUnprotectedHeader must match');
assert.deepEqual(decryptWithHeadersResult.unprotectedHeader, recipientHeader, 'unprotectedHeader must match');

const helperWithHeaders = await decryptFlattened(jweWithHeaders, secretKey);
assert.deepEqual(helperWithHeaders.sharedUnprotectedHeader, sharedHeader);
assert.deepEqual(helperWithHeaders.unprotectedHeader, recipientHeader);

// 4. Additional Authenticated Data (AAD): verifies and returns Additional Authenticated Data (AAD) present in Flattened JWE
const aadBytes = encoder.encode('auth-context-v1');
const encWithAad = new FlattenedEncrypt(plaintextBytes);
encWithAad.setProtectedHeader({ alg: 'dir', enc: 'A256GCM' });
encWithAad.setAdditionalAuthenticatedData(aadBytes);
const jweWithAad = await encWithAad.encrypt(secretKey);

const decryptWithAadResult = await flattenedDecrypt(jweWithAad, secretKey);
assert.equal(decoder.decode(decryptWithAadResult.plaintext), payloadText);
assert.ok(decryptWithAadResult.additionalAuthenticatedData instanceof Uint8Array, 'AAD must be Uint8Array');
assert.deepEqual(decryptWithAadResult.additionalAuthenticatedData, aadBytes, 'AAD must match original bytes');

const helperWithAad = await decryptFlattened(jweWithAad, secretKey);
assert.deepEqual(helperWithAad.additionalAuthenticatedData, aadBytes);

// 5. Asymmetric key decryption: supports asymmetric key decryption using ECDH-ES key agreement
const { publicKey, privateKey } = await generateKeyPair('ECDH-ES');
const encAsymmetric = new FlattenedEncrypt(plaintextBytes);
encAsymmetric.setProtectedHeader({ alg: 'ECDH-ES', enc: 'A256GCM' });
const jweAsymmetric = await encAsymmetric.encrypt(publicKey);

const decryptAsymResult = await flattenedDecrypt(jweAsymmetric, privateKey);
assert.equal(decoder.decode(decryptAsymResult.plaintext), payloadText);
assert.equal(decryptAsymResult.protectedHeader.alg, 'ECDH-ES');
assert.equal(decryptAsymResult.protectedHeader.enc, 'A256GCM');

// 6. Dynamic key resolver callback: accepts a key resolver callback function for dynamic key selection
let resolverCalled = false;
const keyResolver = async (protectedHeader, token) => {
  resolverCalled = true;
  assert.equal(protectedHeader.alg, 'dir');
  assert.equal(protectedHeader.enc, 'A256GCM');
  assert.equal(typeof token, 'object');
  return secretKey;
};

const decryptResolvedResult = await flattenedDecrypt(jwe, keyResolver);
assert.ok(resolverCalled, 'Key resolver callback must be invoked during decryption');
assert.equal(decoder.decode(decryptResolvedResult.plaintext), payloadText);

// 7. Algorithm restrictions options: enforces keyManagementAlgorithms and contentEncryptionAlgorithms options restrictions
await assert.rejects(
  async () => {
    await flattenedDecrypt(jwe, secretKey, { keyManagementAlgorithms: ['ECDH-ES'] });
  },
  (err) => err instanceof Error,
  'Disallowed keyManagementAlgorithms must reject decryption'
);

await assert.rejects(
  async () => {
    await flattenedDecrypt(jwe, secretKey, { contentEncryptionAlgorithms: ['A128CBC-HS256'] });
  },
  (err) => err instanceof Error,
  'Disallowed contentEncryptionAlgorithms must reject decryption'
);

const allowedOptionsResult = await flattenedDecrypt(jwe, secretKey, {
  keyManagementAlgorithms: ['dir'],
  contentEncryptionAlgorithms: ['A256GCM']
});
assert.equal(decoder.decode(allowedOptionsResult.plaintext), payloadText, 'Allowed algorithms must successfully decrypt');

// 8. Tampering rejection: rejects decryption when ciphertext, tag, or protected header is tampered with
const tamperedCiphertextJwe = {
  ...jwe,
  ciphertext: jwe.ciphertext.slice(0, -4) + 'AAAA'
};
await assert.rejects(
  async () => {
    await flattenedDecrypt(tamperedCiphertextJwe, secretKey);
  },
  (err) => err instanceof Error,
  'Tampered ciphertext must reject decryption'
);

const tamperedTagJwe = {
  ...jwe,
  tag: jwe.tag.slice(0, -4) + 'AAAA'
};
await assert.rejects(
  async () => {
    await flattenedDecrypt(tamperedTagJwe, secretKey);
  },
  (err) => err instanceof Error,
  'Tampered auth tag must reject decryption'
);

const tamperedProtectedHeaderJwe = {
  ...jwe,
  protected: jwe.protected.slice(0, -4) + 'AAAA'
};
await assert.rejects(
  async () => {
    await flattenedDecrypt(tamperedProtectedHeaderJwe, secretKey);
  },
  (err) => err instanceof Error,
  'Tampered protected header must reject decryption'
);

console.log('Contract tests passed successfully.');