How Wrap works

Wrap is an open source URL shortener written in pure Go using only the standard library. Every wrapped URL produces both a short Base62 alias and a self-verifying stateless link signed with HMAC-SHA256.

Architecture

Short aliases (/:code): 6-character cryptographic Base62 codes or custom slugs stored in a thread-safe memory store with atomic JSON snapshots and live click counting.
Stateless tokens (/w/:token): Raw Flate compressed URLs paired with an 8-byte expiration timestamp and an 80-bit HMAC-SHA256 authentication tag. Resolves permanently with zero database lookups.
SSRF network guard: Blocks non-HTTP(S) schemes, embedded credentials, loopback addresses, RFC 1918 private networks, link-local cloud metadata (169.254.169.254), and CGNAT ranges.
Token bucket rate limiter: Per-IP token buckets protect link creation (6 burst), visitor redirects (25 burst), and telemetry lookups (15 burst) with standard X-RateLimit headers.

HTTP API Reference

POST /api/shorten: Accepts JSON {"url": "https://...", "alias": "optional", "ttl": "7d"}. Supported TTL values: never, 1h, 24h, 7d, 30d.
GET /:code: Issues a 307 Temporary Redirect to the destination URL with Referrer-Policy: no-referrer and increments the route click counter.
GET /w/:token: Verifies the constant-time HMAC-SHA256 tag and expiration timestamp, decompresses the URL, and issues a 307 Temporary Redirect.
GET /api/stats?code=:code: Returns JSON telemetry including total clicks, creation timestamp, last visited timestamp, expiration time, and referrer host counts.

Terminal Usage

You can shorten URLs and inspect redirect telemetry directly from a terminal using curl.

Create a short link

curl -s -X POST "https://wrap.thgenius.xyz/api/shorten" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.thgenius.xyz","alias":"hub","ttl":"7d"}'

Inspect redirect headers and rate-limit status

curl -I "https://wrap.thgenius.xyz/hub"

Query live click telemetry

curl -s "https://wrap.thgenius.xyz/api/stats?code=hub"

Ready to shorten a link?

Open the router to create a short code or stateless token.

Open Router →