uuidkey

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

![License](https://raw.githubusercontent.com/tanhv90/uuidkey/master/LICENSE)

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
`

$3

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

$3

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:

`sh
npm i uuidkey
`

Usage

`typescript
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'
}
*/
``