hono 4.13.3: sign

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 hono.sign in pkg:npm/hono@4.13.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/hono@4.13.3
Demonstrate these symbols/APIs:
  - hono.sign

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:9cb8d41e17c697995ac5690d2b4e8ab702e96b9ac9a25c7714b647c6c2c1c0c9","contract":["sign generates a signed JWT string with three dot-separated base64url segments for a payload and secret","sign defaults to HS256 algorithm and sets typ to JWT in the token header","sign encodes payload claims into the middle base64url segment","sign supports alternative HMAC algorithms including HS384 and HS512","sign produces distinct signatures when payload or secret changes","sign rejects unsupported signing algorithms with an error"],"goal":"verify hono.sign in pkg:npm/hono@4.13.3","kind":"HOW","packages":["pkg:npm/hono@4.13.3"],"schemaVersion":1,"symbols":["hono.sign"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/hono@4.13.3"],"schemaVersion":1,"subject":"pkg:npm/hono@4.13.3","symbols":["hono.sign"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-hono-sign",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-hono-sign",
      "version": "1.0.0",
      "dependencies": {
        "hono": "4.13.3"
      }
    },
    "node_modules/hono": {
      "version": "4.13.3",
      "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.3.tgz",
      "integrity": "sha512-r8AO2mYHoLxSHkgafNeC/BXyb2vWRxD3jem4Ts+ptav8oTG5FIRifAjuJEmZI4bSvvc2ns0GxmIYiZnHqN3mMw==",
      "license": "MIT",
      "engines": {
        "node": ">=16.9.0"
      }
    }
  }
}

{
  "name": "sample-hono-sign",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification for hono.sign in pkg:npm/hono@4.13.3",
  "type": "module",
  "dependencies": {
    "hono": "4.13.3"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify hono.sign in pkg:npm/hono@4.13.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/hono@4.13.3"
  ],
  "symbols": [
    "hono.sign"
  ]
}

import { sign } from 'hono/jwt';
import { Jwt } from 'hono/utils/jwt';

/**
 * Signs a JWT payload using Hono's sign utility.
 *
 * @param {object} payload - Claims object to include in JWT payload.
 * @param {string|CryptoKey} secret - Secret key for signing.
 * @param {string} [alg='HS256'] - Algorithm to use for signing.
 * @returns {Promise<string>} Signed JWT string with header, payload, and signature segments.
 */
export async function createSignedToken(payload, secret, alg = 'HS256') {
  return await sign(payload, secret, alg);
}

export { sign, Jwt };

import assert from 'node:assert/strict';
import { createSignedToken, sign, Jwt } from '../src/index.mjs';

const SECRET_KEY = 'sample-secret-signing-key-32b!';

// Contract 1: sign generates a signed JWT string with three dot-separated base64url segments for a payload and secret
{
  assert.equal(typeof sign, 'function', 'sign must be a function');
  assert.equal(typeof createSignedToken, 'function', 'createSignedToken must be a function');
  assert.equal(Jwt.sign, sign, 'Jwt.sign must equal sign');

  const payload = { sub: 'user_1001', role: 'admin', iat: 1700000000 };
  const token = await createSignedToken(payload, SECRET_KEY);

  assert.equal(typeof token, 'string', 'Token must be a string');
  const parts = token.split('.');
  assert.equal(parts.length, 3, 'JWT must contain exactly three parts (header.payload.signature)');
  assert.ok(parts[0].length > 0, 'Header part must not be empty');
  assert.ok(parts[1].length > 0, 'Payload part must not be empty');
  assert.ok(parts[2].length > 0, 'Signature part must not be empty');
}

// Contract 2: sign defaults to HS256 algorithm and sets typ to JWT in the token header
{
  const payload = { sub: 'user_1002' };
  const token = await sign(payload, SECRET_KEY);

  const parts = token.split('.');
  const headerJson = Buffer.from(parts[0], 'base64url').toString('utf-8');
  const header = JSON.parse(headerJson);

  assert.equal(header.alg, 'HS256', 'Default algorithm in header must be HS256');
  assert.equal(header.typ, 'JWT', 'Header typ must be JWT');
}

// Contract 3: sign encodes payload claims into the middle base64url segment
{
  const payload = { sub: 'user_1003', name: 'Test User', permissions: ['read', 'write'], active: true };
  const token = await createSignedToken(payload, SECRET_KEY);

  const parts = token.split('.');
  const payloadJson = Buffer.from(parts[1], 'base64url').toString('utf-8');
  const decodedPayload = JSON.parse(payloadJson);

  assert.equal(decodedPayload.sub, 'user_1003');
  assert.equal(decodedPayload.name, 'Test User');
  assert.deepEqual(decodedPayload.permissions, ['read', 'write']);
  assert.equal(decodedPayload.active, true);
}

// Contract 4: sign supports alternative HMAC algorithms including HS384 and HS512
{
  const payload = { sub: 'user_1004' };

  const token384 = await sign(payload, SECRET_KEY, 'HS384');
  const header384 = JSON.parse(Buffer.from(token384.split('.')[0], 'base64url').toString('utf-8'));
  assert.equal(header384.alg, 'HS384', 'Algorithm in header must be HS384');

  const token512 = await sign(payload, SECRET_KEY, 'HS512');
  const header512 = JSON.parse(Buffer.from(token512.split('.')[0], 'base64url').toString('utf-8'));
  assert.equal(header512.alg, 'HS512', 'Algorithm in header must be HS512');
}

// Contract 5: sign produces distinct signatures when payload or secret changes
{
  const payload1 = { sub: 'user_1005', role: 'member' };
  const payload2 = { sub: 'user_1006', role: 'member' };
  const differentSecret = 'another-different-secret-key-32!';

  const tokenBase = await sign(payload1, SECRET_KEY);
  const tokenDifferentPayload = await sign(payload2, SECRET_KEY);
  const tokenDifferentSecret = await sign(payload1, differentSecret);

  const sigBase = tokenBase.split('.')[2];
  const sigDiffPayload = tokenDifferentPayload.split('.')[2];
  const sigDiffSecret = tokenDifferentSecret.split('.')[2];

  assert.notEqual(sigBase, sigDiffPayload, 'Different payloads must produce different signatures');
  assert.notEqual(sigBase, sigDiffSecret, 'Different secrets must produce different signatures');
}

// Contract 6: sign rejects unsupported signing algorithms with an error
{
  const payload = { sub: 'user_1007' };
  await assert.rejects(
    async () => {
      await sign(payload, SECRET_KEY, 'UNSUPPORTED_ALG');
    },
    (err) => {
      assert.ok(err instanceof Error);
      return true;
    },
    'sign must reject unsupported algorithm'
  );
}

console.log('All contracts for hono.sign in pkg:npm/hono@4.13.3 passed.');