uuidkey 包通过 Base32-Crockford 编码器将 UUID 编码为可读的 Key 格式。
_ _ _ _ ___ ____ _ __
| | | || | | ||_ _| _ \ | |/ /___ _ _
| | | || | | | | || | | | | ' // _ \ | | |
| |_| || |_| | | || |_| | | . \ __/ |_| |
\___/ \___/ |___|____/ |_|\_\___|\__, |
|___/ The uuidkey package encodes UUIDs to a readable Key format via the Base32-Crockford codec.
Note: Thanks to everyone for the feedback and suggestions from the original article, we learned a lot and made improvements to follow the GitHub Secret Scanning format (with checksum) and added additional entropy options to ensure UUIDv7 encoding can be used in a wide variety of use cases. You can still use the
Encodefunction to generate aKeytype without the GitHub prefix format and additional entropy - but we recommend using theNewAPIKeyfunction with an 8 character prefix to stay symetrical ;P
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).
Implementation Note: As of v1.1.0, this package uses only the Go standard library's
encoding/base32for Base32-Crockford encoding, removing the external dependency ongithub.com/richardlehane/crock32. The implementation maintains full backward compatibility while providing constant-time encoding operations.
The uuidkey package has been implemented in several programming languages:
Go - This repository (official implementation)
Node.js/TypeScript - By @tanhv90
.NET/C# - By @fremenkiel
Want to add your implementation? Feel free to open a PR to add it to this list!
AGNTSTNP_38QARV01ET0G6Z2CJD9VA2ZZAR0XJJLSO7WBNWY3F_A1B2C3D8
└─────┘ └──────────────────────────┘└────────────┘ └──────┘
Prefix Key (crock32 UUID) Entropy ChecksumCompatible with any UUID library following RFC 4122 specification. Officially tested with:
To install the uuidkey package, use the following command:
go get github.com/agentstation/uuidkeyTo use the uuidkey package in your Go code, follow these steps:
import "github.com/agentstation/uuidkey"…// With hyphens (default)
key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X
// Without hyphens
key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d", uuidkey.WithoutHyphens)
fmt.Println(key) // Output: 38QARV01ET0G6Z2CJD9VA2ZZAR0X// With hyphens
key, _ := uuidkey.Parse("38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X")
uuid, err := key.UUID()
if err != nil {
log.Fatal("Error:", err)
}
fmt.Println(uuid) // Output: d1756360-5da0-40df-9926-a76abff5601d
// Without hyphens
key, _ := uuidkey.Parse("38QARV01ET0G6Z2CJD9VA2ZZAR0X")
uuid, err := key.UUID()
if err != nil {
log.Fatal("Error:", err)
}
fmt.Println(uuid) // Output: d1756360-5da0-40df-9926-a76abff5601dkey, _ := uuidkey.Parse("38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X")
uuid, err := key.Decode()
if err != nil {
log.Fatal("Error:", err)
}
fmt.Println(uuid) // Output: d1756360-5da0-40df-9926-a76abff5601d…The uuidkey CLI provides a command-line interface for encoding/decoding UUIDs and generating API keys.
go install github.com/agentstation/uuidkey/cmd/uuidkey@latestPre-built binaries are available on the releases page for:
The CLI supports smart command detection - if no input is provided, it generates new values.
…uuidkey uuidGenerate or work with UUIDs
--version, -v: UUID version (4, 6, or 7; default 4)--time, -t: Custom timestamp for v6/v7 (RFC3339 format)uuidkey keyEncode UUIDs to Base32-Crockford keys or decode keys back to UUIDs
uuidkey apikeyGenerate or parse API keys with prefix, entropy, and checksum
--prefix: Set the prefix for new API keys (required for generation)--entropy: Set entropy bits (128, 160, or 256; default 160)uuidkey encodeExplicitly encode a UUID to Base32-Crockford
uuidkey decodeExplicitly decode a Base32-Crockford key to UUID
uuidkey versionDisplay version and build information
--verify: Calculate and display binary checksum--verify-online: Verify checksum against GitHub releases--json, -j: Output in JSON format--quiet, -q: Only output the result valueimport "github.com/agentstation/uuidkey"Package uuidkey provides Crockford Base32 encoding that's compatible with the original crock32 number-based approach
Package uuidkey encodes UUIDs to a readable Key format via the Base32-Crockford codec.
Key validation constraint constants
…APIKey represents a compound key consisting of four parts or segments: - Prefix: A company or application identifier (e.g., "AGNTSTNP") - Key: A UUID-based identifier encoded in Base32-Crockford - Entropy: Additional segment of random data for increased uniqueness - Checksum: CRC32 checksum of the previous components (8 characters)
Format:
[Prefix]_[UUID Key][Entropy]_[Checksum]
AGNTSTNP_38QARV01ET0G6Z2CJD9VA2ZZAR0XJJLSO7WBNWY3F_A1B2C3D8
└─────┘ └──────────────────────────┘└────────────┘ └──────┘
Prefix Key (crock32 UUID) Entropy Checksumtype APIKey struct {
Prefix string
Key Key
Entropy string
Checksum string
}func NewAPIKey(prefix, uuid string, opts ...Option) (APIKey, error)NewAPIKey creates a new APIKey from a string prefix, string UUID, and options.
func NewAPIKeyFromBytes(prefix string, uuid [16]byte, opts ...Option) (APIKey, error)NewAPIKeyFromBytes creates a new APIKey from a string prefix, [16]byte UUID, and options.
func ParseAPIKey(apikey string) (APIKey, error)ParseAPIKey will parse a given APIKey string into an APIKey type.
func (a APIKey) String() stringString returns the complete API key as a string with all components joined
Key is a UUID Key string.
type Key stringfunc Encode(uuid string, opts ...Option) (Key, error)Encode will encode a given UUID string into a Key. It pre-allocates the exact string capacity needed for better performance.
func EncodeBytes(uuid [16]byte, opts ...Option) (Key, error)EncodeBytes encodes a [16]byte UUID into a Key.
func Parse(key string) (Key, error)Parse converts a Key formatted string into a Key type.
func (k Key) Bytes() ([16]byte, error)Bytes converts a Key to a [16]byte UUID.
func (k Key) Decode() (string, error)Decode will decode a given Key into a UUID string with basic length validation.
func (k Key) IsValid() boolIsValid verifies if a given Key follows the correct format. The format should be:
func (k Key) String() stringString will convert your Key into a string.
func (k Key) UUID() (string, error)UUID will validate and convert a given Key into a UUID string.
Option is a function that configures options
type Option func(c *config)With128BitEntropy expects 128 bits of entropy in the APIKey
var With128BitEntropy Option = func(c *config) {
c.entropySize = EntropyBits128
}With160BitEntropy expects 160 bits of entropy in the APIKey
var With160BitEntropy Option = func(c *config) {
c.entropySize = EntropyBits160
}With256BitEntropy expects 256 bits of entropy in the APIKey
var With256BitEntropy Option = func(c *config) {
c.entropySize = EntropyBits256
}WithoutHyphens expects no hyphens in the Key
var WithoutHyphens Option = func(c *config) {
c.hyphens = false
}Generated by gomarkdoc
…All tests now pass reliably. The Cobra state pollution issue has been resolved by using fresh command instances for each test.
Note: These benchmarks were run on an Apple M2 Max CPU with 12 cores (8 performance and 4 efficiency) and 32 GB of memory, running macOS 14.6.1. The results are not representative of all systems, but should give you a general idea of the performance of the package. I was running other processes on the machine while running the benchmarks.
Your mileage may vary.
…暂无开放 Issues,或尚未同步最近议题。