_   _  _   _  ___ ____     _  __          
                        | | | || | | ||_ _|  _ \   | |/ /___ _   _ 
                        | | | || | | | | || | | |  | ' // _ \ | | |
                        | |_| || |_| | | || |_| |  | . \  __/ |_| |
                         \___/  \___/ |___|____/   |_|\_\___|\__, |
                                                             |___/ 

A Node.js implementation of the agentstation/uuidkey library, originally written in Go.

Overview

The uuidkey package generates secure, readable API keys by encoding UUIDs using Base32-Crockford with additional security features.

You can use the uuidkey package to generate API keys for your application using the newAPIKey function (recommended to guarantee at least 128 bits of entropy and follow the GitHub Secret Scanning format) or the encode function (to generate just a Key type).

API Key Format

AGNTSTNP_38QARV01ET0G6Z2CJD9VA2ZZAR0XJJLSO7WBNWY3F_A1B2C3D8
└─────┘ └──────────────────────────┘└────────────┘ └──────┘
Prefix        Key (crock32 UUID)        Entropy      Checksum

Components

1. Prefix - Company/application identifier (e.g., "AGNTSTNP")
2. Key - Base32-Crockford encoded UUID
3. Entropy - Additional random data (128, 160, or 256 bits)
4. Checksum - CRC32 checksum (8 characters) for validation

Security Features

1. Secret Scanning - Formatted for GitHub Secret Scanning detection
2. Validation - CRC32 checksum for error detection and validation
3. Entropy Options - Configurable entropy levels that ensure UUIDv7 security (128, 160, or 256 bits)

Installation

To install the uuidkey package, use the following command:

npm i uuidkey

Usage

import { newAPIKey, parse, Options } from 'uuidkey';

let apiKey = newAPIKey('MYPREFIX', 'd1756360-5da0-40df-9926-a76abff5601d');
console.log(apiKey)
/*
APIKey {
  prefix: 'MYPREFIX',
  key: Key { value: '38QARV01ET0G6Z2CJD9VA2ZZAR0X' },
  entropy: 'SMJP4AMEEWHGZDCGDDBBF',
  checksum: '86887EAC'
}
*/
console.log(apiKey.toString())
// MYPREFIX_38QARV01ET0G6Z2CJD9VA2ZZAR0XSMJP4AMEEWHGZDCGDDBBF_86887EAC

apiKey = newAPIKey('MYPREFIX', 'd1756360-5da0-40df-9926-a76abff5601d', Options.With128BitEntropy);
console.log(apiKey)
/*
APIKey {
  prefix: 'MYPREFIX',
  key: Key { value: '38QARV01ET0G6Z2CJD9VA2ZZAR0X' },
  entropy: '1R3QJNHCBA9RCX',
  checksum: 'B51D4BAB'
}
*/

apiKey = parse('MYPREFIX_38QARV01ET0G6Z2CJD9VA2ZZAR0XSMJP4AMEEWHGZDCGDDBBF_86887EAC');
console.log(apiKey)
/*
APIKey {
  prefix: 'MYPREFIX',
  key: Key { value: '38QARV01ET0G6Z2CJD9VA2ZZAR0X' },
  entropy: 'SMJP4AMEEWHGZDCGDDBBF',
  checksum: '86887EAC'
}
*/