urlsigner

README

🔐 Go URL Signer

A lightweight Go library for generating and verifying signed, expirable URLs using HMAC (SHA-256 by default). Perfect for secure link sharing, protected downloads, and time-limited access.

---

Features

• HMAC-based signing using any crypto.Hash
• Expirable URL support (exp query param)
• Easy to use with string or url.URL
• Constant-time signature verification
• Configurable field names and hash algorithm

Installation

go get github.com/ionutmilica/urlsigner

Usage

Sign a URL (permanent)

package main

import (
    "fmt"
    "github.com/ionutmilica/urlsigner"
)

func main() {
    signer := urlsigner.New("my-secret-key")

    signedURL, err := signer.SignURL("https://my-app.dev/resource?id=123")
    if err != nil {
        panic(err)
    }

    fmt.Println("Signed URL:", signedURL)
}

Sign a URL with Expiration

package main

import (
    "fmt"
    "time"
    "github.com/ionutmilica/urlsigner"
)

func main() {
    signer := urlsigner.New("my-secret-key")
    expiration := time.Now().Add(30 * time.Minute)

    signedURL, err := signer.SignURLWithExpiry("https://my-app.dev/protected", expiration)
    if err != nil {
        panic(err)
    }

    fmt.Println("Signed temporary URL:", signedURL)
}

Verify a Signed URL

err := signer.VerifyURL(signedURL)
if err != nil {
    fmt.Println("Invalid or expired URL:", err)
} else {
    fmt.Println("Valid URL ✅")
}

Use with url.URL Objects Directly

u, _ := url.Parse("https://my-app.dev/page")
signed := signer.Sign(*u)

err := signer.Verify(signed)

Signing Arbitrary Payloads

Default settings

signature := urlsigner.Sign(sha256.New, "key", "payload")
isValid := urlsigner.Verify(signature, "expected-signature")

Custom encoding

signature := urlsigner.SignWithEncoding(sha256.New, HexEncoding, "key", "payload")
isValid := urlsigner.VerifyWithEncoding(HexEncoding, signature, "expected-signature")

Custom Configuration

signer := urlsigner.New("my-secret-key",
    urlsigner.WithSignatureField("signature"),
    urlsigner.WithExpirationField("expires"),
    urlsigner.WithAlgorithm(sha512.New),
    urlsigner.WithEncoding(HexEncoding)
)

License

MIT License — see LICENSE for details.

Documentation

Index

• Variables
• func Sign(algorithm func() hash.Hash, key, payload string) string
• func SignWithEncoding(algorithm func() hash.Hash, encoding Encoding, key, payload string) string
• func Verify(a, b string) bool
• func VerifyWithEncoding(encoding Encoding, b, a string) bool
• func WithAlgorithm(alg func() hash.Hash) func(*SignerProvider)
• func WithEncoding(encoding Encoding) func(*SignerProvider)
• func WithExpirationField(name string) func(*SignerProvider)
• func WithSignatureField(name string) func(*SignerProvider)
• type Encoding
• type SignerProvider
  • func New(secretKey string, opts ...func(*SignerProvider)) *SignerProvider
  • func (p *SignerProvider) Sign(u url.URL) url.URL
  • func (p *SignerProvider) SignURL(rawURL string) (string, error)
  • func (p *SignerProvider) SignURLWithExpiry(rawURL string, expireAt time.Time) (string, error)
  • func (p *SignerProvider) SignURLWithTTL(rawURL string, ttl time.Duration) (string, error)
  • func (p *SignerProvider) SignWithExpiry(u url.URL, expireAt time.Time) url.URL
  • func (p *SignerProvider) SignWithTTL(u url.URL, ttl time.Duration) url.URL
  • func (p *SignerProvider) Verify(u url.URL) error
  • func (p *SignerProvider) VerifyURL(rawURL string) error

Variables

var (
	ErrInvalidSignature = errors.New("invalid signature")
	ErrExpired          = errors.New("url has expired")
	ErrParseFailure     = errors.New("failed to parse URL")
)

var Base64Encoding = &base64Encoding{}

var HexEncoding = &hexEncoding{}

Functions

func Sign

func Sign(algorithm func() hash.Hash, key, payload string) string

Sign will create a new signature based on a key and a string payload It is required to choose a hash algorithm

func SignWithEncoding

func SignWithEncoding(algorithm func() hash.Hash, encoding Encoding, key, payload string) string

func Verify

func Verify(a, b string) bool

Verify will tell if two string signatures are equal

func VerifyWithEncoding

func VerifyWithEncoding(encoding Encoding, b, a string) bool

func WithAlgorithm

func WithAlgorithm(alg func() hash.Hash) func(*SignerProvider)

WithAlgorithm allows overriding of the internal hashing algorithm

func WithEncoding

func WithEncoding(encoding Encoding) func(*SignerProvider)

WithEncoding allows overriding of the internal encoding mechanism

func WithExpirationField

func WithExpirationField(name string) func(*SignerProvider)

WithExpirationField allows overriding of the internal field name for expiration

func WithSignatureField

func WithSignatureField(name string) func(*SignerProvider)

WithSignatureField allows overriding of the internal field name for signature

Types

type Encoding

type Encoding interface {
	EncodeToString(src []byte) string
	DecodeString(s string) ([]byte, error)
}

type SignerProvider

type SignerProvider struct {
	// contains filtered or unexported fields
}

SignerProvider is used to sign and verify urls.

func New

func New(secretKey string, opts ...func(*SignerProvider)) *SignerProvider

New will create a new SignerProvider.

urlsigner.New("secret-key")

func (*SignerProvider) Sign

func (p *SignerProvider) Sign(u url.URL) url.URL

Sign will sign a URL object returning it updated to include the signature

func (*SignerProvider) SignURL

func (p *SignerProvider) SignURL(rawURL string) (string, error)

SignURL acts like Sign method but accepts the url as string instead of url.URL

func (*SignerProvider) SignURLWithExpiry

func (p *SignerProvider) SignURLWithExpiry(rawURL string, expireAt time.Time) (string, error)

SignURLWithExpiry acts like SignWithExpiry method but accepts the url as string instead of url.URL

func (*SignerProvider) SignURLWithTTL

func (p *SignerProvider) SignURLWithTTL(rawURL string, ttl time.Duration) (string, error)

func (*SignerProvider) SignWithExpiry

func (p *SignerProvider) SignWithExpiry(u url.URL, expireAt time.Time) url.URL

SignWithExpiry will sign a URL object for a limited period of time returning it updated with two new query strings: signature, expiration

func (*SignerProvider) SignWithTTL

func (p *SignerProvider) SignWithTTL(u url.URL, ttl time.Duration) url.URL

SignWithTTL will sign a URL object for a limited period of time returning it updated with two new query strings: signature, expiration

func (*SignerProvider) Verify

func (p *SignerProvider) Verify(u url.URL) error

Verify will check a URL object against its signature This signature should be provided by the url itself in a query string

func (*SignerProvider) VerifyURL

func (p *SignerProvider) VerifyURL(rawURL string) error

VerifyURL acts like Verify method but accepts the url as string instead of url.URL