urlsigner

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 12, 2025 License: MIT Imports: 9 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalidSignature = errors.New("invalid signature")
	ErrExpired          = errors.New("url has expired")
	ErrParseFailure     = errors.New("failed to parse URL")
)
View Source
var Base64Encoding = &base64Encoding{}
View Source
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 added in v1.1.0

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 added in v1.1.0

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

func WithAlgorithm added in v1.1.0

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

WithAlgorithm allows overriding of the internal hashing algorithm

func WithEncoding added in v1.1.0

func WithEncoding(encoding Encoding) func(*SignerProvider)

WithEncoding allows overriding of the internal encoding mechanism

func WithExpirationField added in v1.1.0

func WithExpirationField(name string) func(*SignerProvider)

WithExpirationField allows overriding of the internal field name for expiration

func WithSignatureField added in v1.1.0

func WithSignatureField(name string) func(*SignerProvider)

WithSignatureField allows overriding of the internal field name for signature

Types

type Encoding added in v1.1.0

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 added in v1.0.0

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 added in v1.0.0

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

func (*SignerProvider) SignWithExpiry added in v1.0.0

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 added in v1.0.0

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL