@clipr/worker 0.0.5

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@clipr/worker",
+  "version": "0.0.5",
+  "description": "Cloudflare Worker for clipr URL redirects",
+  "type": "module",
+  "main": "./src/index.ts",
+  "dependencies": {
+    "hono": "^4.7.0",
+    "qrcode": "^1.5.4",
+    "@clipr/core": "0.0.6"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250327.0",
+    "@types/node": "^25.5.0",
+    "@types/qrcode": "^1.5.5",
+    "vitest": "^4.1.2",
+    "wrangler": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hammadxcm/clipr",
+    "directory": "packages/worker"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "build": "wrangler deploy --dry-run --outdir=dist",
+    "deploy": "wrangler deploy",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,85 @@
+/**
+ * PBKDF2 password hashing via Web Crypto API.
+ * Uses a random 16-byte salt with 100,000 iterations.
+ * Format: "hex_salt:hex_hash"
+ */
+
+function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+function fromHex(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = Number.parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+const ITERATIONS = 100_000;
+const HASH_ALGO = 'SHA-256';
+const KEY_LENGTH = 256;
+
+/**
+ * Hash a password with PBKDF2 (100k iterations).
+ * @returns "hex_salt:hex_hash"
+ */
+export async function hashPassword(password: string): Promise<string> {
+  const salt = new Uint8Array(16);
+  crypto.getRandomValues(salt);
+
+  const encoder = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(password),
+    'PBKDF2',
+    false,
+    ['deriveBits'],
+  );
+
+  const derivedBits = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', salt, iterations: ITERATIONS, hash: HASH_ALGO },
+    keyMaterial,
+    KEY_LENGTH,
+  );
+
+  return `${toHex(salt)}:${toHex(new Uint8Array(derivedBits))}`;
+}
+
+/**
+ * Verify a password against a stored "hex_salt:hex_hash" string.
+ * Uses constant-time comparison to prevent timing attacks.
+ */
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const [saltHex, expectedHashHex] = stored.split(':');
+  if (!saltHex || !expectedHashHex) return false;
+
+  const salt = fromHex(saltHex);
+  const encoder = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(password),
+    'PBKDF2',
+    false,
+    ['deriveBits'],
+  );
+
+  const derivedBits = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', salt, iterations: ITERATIONS, hash: HASH_ALGO },
+    keyMaterial,
+    KEY_LENGTH,
+  );
+
+  const actualBytes = new Uint8Array(derivedBits);
+  const expectedBytes = fromHex(expectedHashHex);
+
+  // Constant-time comparison
+  if (actualBytes.length !== expectedBytes.length) return false;
+  let diff = 0;
+  for (let i = 0; i < actualBytes.length; i++) {
+    diff |= actualBytes[i]! ^ expectedBytes[i]!;
+  }
+  return diff === 0;
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { authMiddleware } from './middleware/auth.js';
+import { handleHealth } from './routes/health.js';
+import { handleExport, handleImport } from './routes/import-export.js';
+import {
+  handleDeleteLink,
+  handleGetLink,
+  handleListLinks,
+  handleUpdateLink,
+} from './routes/links.js';
+import { handlePasswordPage, handlePasswordVerify } from './routes/password.js';
+import { handleQr } from './routes/qr.js';
+import { handleRedirect } from './routes/redirect.js';
+import { handleShorten } from './routes/shorten.js';
+import { handleStats } from './routes/stats.js';
+import type { Env } from './types.js';
+
+const app = new Hono<{ Bindings: Env }>();
+
+// CORS — restrict API access
+app.use(
+  '/api/*',
+  cors({
+    origin: (origin) => origin || '*',
+    allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+    allowHeaders: ['Authorization', 'Content-Type'],
+    maxAge: 86400,
+  }),
+);
+
+// Auth middleware — applied to all routes, skips public ones internally
+app.use('*', authMiddleware);
+
+// --- Public routes ---
+app.get('/health', handleHealth);
+app.get('/password/:code', handlePasswordPage);
+app.post('/password/:code', handlePasswordVerify);
+
+// --- API routes (protected by auth middleware) ---
+app.post('/api/shorten', handleShorten);
+
+app.get('/api/links', handleListLinks);
+app.get('/api/links/:code', handleGetLink);
+app.put('/api/links/:code', handleUpdateLink);
+app.delete('/api/links/:code', handleDeleteLink);
+
+app.get('/api/stats/:code', handleStats);
+app.get('/api/qr/:code', handleQr);
+
+app.post('/api/import', handleImport);
+app.get('/api/export', handleExport);
+
+// --- Catch-all redirect (public) ---
+app.get('/:slug', handleRedirect);
+
+app.notFound((c) => c.text('Not Found', 404));
+
+export default app;

package/src/kv-backend.test.ts

@@ -0,0 +1,56 @@
+import { SlugConflictError } from '@clipr/core';
+import { describe, expect, it } from 'vitest';
+import { KvBackend } from './kv-backend.js';
+import { createMockKV } from './test-utils.js';
+
+function makeEntry(slug: string, url = 'https://example.com') {
+  return { slug, url, createdAt: new Date().toISOString() };
+}
+
+describe('KvBackend', () => {
+  it('stores and retrieves entries', async () => {
+    const backend = new KvBackend(createMockKV());
+    await backend.set(makeEntry('abc', 'https://test.com'));
+    const entry = await backend.get('abc');
+    expect(entry?.url).toBe('https://test.com');
+  });
+
+  it('returns undefined for missing slugs', async () => {
+    const backend = new KvBackend(createMockKV());
+    expect(await backend.get('nope')).toBeUndefined();
+  });
+
+  it('throws SlugConflictError on duplicate', async () => {
+    const backend = new KvBackend(createMockKV());
+    await backend.set(makeEntry('dupe'));
+    await expect(backend.set(makeEntry('dupe'))).rejects.toThrow(SlugConflictError);
+  });
+
+  it('deletes entries', async () => {
+    const backend = new KvBackend(createMockKV());
+    await backend.set(makeEntry('del'));
+    expect(await backend.delete('del')).toBe(true);
+    expect(await backend.get('del')).toBeUndefined();
+  });
+
+  it('returns false when deleting non-existent slug', async () => {
+    const backend = new KvBackend(createMockKV());
+    expect(await backend.delete('ghost')).toBe(false);
+  });
+
+  it('checks existence', async () => {
+    const backend = new KvBackend(createMockKV());
+    await backend.set(makeEntry('exists'));
+    expect(await backend.has('exists')).toBe(true);
+    expect(await backend.has('nope')).toBe(false);
+  });
+
+  it('lists all entries', async () => {
+    const backend = new KvBackend(createMockKV());
+    await backend.set(makeEntry('aaa'));
+    await backend.set(makeEntry('bbb'));
+    const entries = await backend.list();
+    expect(entries).toHaveLength(2);
+    expect(entries.map((e) => e.slug).sort()).toEqual(['aaa', 'bbb']);
+  });
+});

package/src/kv-backend.ts

@@ -0,0 +1,70 @@
+import type { Backend, UrlEntry } from '@clipr/core';
+import { SlugConflictError } from '@clipr/core';
+
+/**
+ * Backend implementation backed by Cloudflare KV.
+ *
+ * Each slug is stored as a separate KV key with the UrlEntry as JSON value.
+ * A special `_index` key holds the list of all slugs for the `list()` method.
+ */
+export class KvBackend implements Backend {
+  constructor(private readonly kv: KVNamespace) {}
+
+  async get(slug: string): Promise<UrlEntry | undefined> {
+    const raw = await this.kv.get(slug, 'text');
+    if (!raw) return undefined;
+    return JSON.parse(raw) as UrlEntry;
+  }
+
+  async set(entry: UrlEntry): Promise<void> {
+    const existing = await this.kv.get(entry.slug, 'text');
+    if (existing) {
+      throw new SlugConflictError(entry.slug);
+    }
+    await this.kv.put(entry.slug, JSON.stringify(entry));
+    await this.addToIndex(entry.slug);
+  }
+
+  async delete(slug: string): Promise<boolean> {
+    const existing = await this.kv.get(slug, 'text');
+    if (!existing) return false;
+    await this.kv.delete(slug);
+    await this.removeFromIndex(slug);
+    return true;
+  }
+
+  async has(slug: string): Promise<boolean> {
+    const val = await this.kv.get(slug, 'text');
+    return val !== null;
+  }
+
+  async list(): Promise<UrlEntry[]> {
+    const slugs = await this.getIndex();
+    const entries: UrlEntry[] = [];
+    for (const slug of slugs) {
+      const entry = await this.get(slug);
+      if (entry) entries.push(entry);
+    }
+    return entries;
+  }
+
+  private async getIndex(): Promise<string[]> {
+    const raw = await this.kv.get('_index', 'text');
+    if (!raw) return [];
+    return JSON.parse(raw) as string[];
+  }
+
+  private async addToIndex(slug: string): Promise<void> {
+    const index = await this.getIndex();
+    if (!index.includes(slug)) {
+      index.push(slug);
+      await this.kv.put('_index', JSON.stringify(index));
+    }
+  }
+
+  private async removeFromIndex(slug: string): Promise<void> {
+    const index = await this.getIndex();
+    const filtered = index.filter((s) => s !== slug);
+    await this.kv.put('_index', JSON.stringify(filtered));
+  }
+}

package/src/kv.ts

@@ -0,0 +1,164 @@
+import type { LinkStats, ShortUrl } from '@clipr/core';
+
+// KV key prefixes
+const URL_PREFIX = 'url:';
+const META_COUNTER = 'meta:counter';
+const STATS_PREFIX = 'stats:';
+const GEO_PREFIX = 'geo:';
+const DEVICE_PREFIX = 'device:';
+const REFERRER_PREFIX = 'referrer:';
+const INDEX_KEY = '_url_index';
+
+/** Get a ShortUrl by code. */
+export async function getUrl(kv: KVNamespace, code: string): Promise<ShortUrl | null> {
+  const raw = await kv.get(`${URL_PREFIX}${code}`, 'text');
+  if (!raw) return null;
+  return JSON.parse(raw) as ShortUrl;
+}
+
+/** Store a ShortUrl by code and add to index. */
+export async function putUrl(kv: KVNamespace, code: string, data: ShortUrl): Promise<void> {
+  await kv.put(`${URL_PREFIX}${code}`, JSON.stringify(data));
+  await addToIndex(kv, code);
+}
+
+/** Delete a ShortUrl by code and remove from index. */
+export async function deleteUrl(kv: KVNamespace, code: string): Promise<boolean> {
+  const existing = await kv.get(`${URL_PREFIX}${code}`, 'text');
+  if (!existing) return false;
+  await kv.delete(`${URL_PREFIX}${code}`);
+  await removeFromIndex(kv, code);
+  return true;
+}
+
+/** List all stored ShortUrl entries. */
+export async function listUrls(kv: KVNamespace): Promise<ShortUrl[]> {
+  const codes = await getIndex(kv);
+  const entries: ShortUrl[] = [];
+  for (const code of codes) {
+    const entry = await getUrl(kv, code);
+    if (entry) entries.push(entry);
+  }
+  return entries;
+}
+
+/** Get the current counter value. */
+export async function getCounter(kv: KVNamespace): Promise<number> {
+  const raw = await kv.get(META_COUNTER, 'text');
+  if (!raw) return 0;
+  return parseInt(raw, 10);
+}
+
+/** Increment the counter and return the new value. */
+export async function incrementCounter(kv: KVNamespace): Promise<number> {
+  const current = await getCounter(kv);
+  const next = current + 1;
+  await kv.put(META_COUNTER, String(next));
+  return next;
+}
+
+/**
+ * Increment a statistics counter for a link.
+ * @param type - 'total' | 'daily' | 'geo' | 'device' | 'referrer'
+ * @param key - The sub-key (e.g., date string, country code, device type, referrer domain).
+ *              Ignored for 'total' type.
+ */
+export async function incrementStat(
+  kv: KVNamespace,
+  code: string,
+  type: 'total' | 'daily' | 'geo' | 'device' | 'referrer',
+  key?: string,
+): Promise<void> {
+  let kvKey: string;
+  switch (type) {
+    case 'total':
+      kvKey = `${STATS_PREFIX}${code}:total`;
+      break;
+    case 'daily':
+      kvKey = `${STATS_PREFIX}${code}:daily:${key}`;
+      break;
+    case 'geo':
+      kvKey = `${GEO_PREFIX}${code}:${key}`;
+      break;
+    case 'device':
+      kvKey = `${DEVICE_PREFIX}${code}:${key}`;
+      break;
+    case 'referrer':
+      kvKey = `${REFERRER_PREFIX}${code}:${key}`;
+      break;
+  }
+  const raw = await kv.get(kvKey, 'text');
+  const current = raw ? parseInt(raw, 10) : 0;
+  await kv.put(kvKey, String(current + 1));
+}
+
+/** Assemble LinkStats for a given code from multiple KV keys. */
+export async function getStats(kv: KVNamespace, code: string): Promise<LinkStats> {
+  const stats: LinkStats = {
+    total: 0,
+    daily: {},
+    geo: {},
+    device: {},
+    referrer: {},
+  };
+
+  // Total clicks
+  const totalRaw = await kv.get(`${STATS_PREFIX}${code}:total`, 'text');
+  if (totalRaw) stats.total = parseInt(totalRaw, 10);
+
+  // Daily stats — list keys with prefix
+  const dailyKeys = await kv.list({ prefix: `${STATS_PREFIX}${code}:daily:` });
+  for (const key of dailyKeys.keys) {
+    const dateStr = key.name.replace(`${STATS_PREFIX}${code}:daily:`, '');
+    const val = await kv.get(key.name, 'text');
+    if (val) stats.daily[dateStr] = parseInt(val, 10);
+  }
+
+  // Geo stats
+  const geoKeys = await kv.list({ prefix: `${GEO_PREFIX}${code}:` });
+  for (const key of geoKeys.keys) {
+    const country = key.name.replace(`${GEO_PREFIX}${code}:`, '');
+    const val = await kv.get(key.name, 'text');
+    if (val) stats.geo[country] = parseInt(val, 10);
+  }
+
+  // Device stats
+  const deviceKeys = await kv.list({ prefix: `${DEVICE_PREFIX}${code}:` });
+  for (const key of deviceKeys.keys) {
+    const device = key.name.replace(`${DEVICE_PREFIX}${code}:`, '');
+    const val = await kv.get(key.name, 'text');
+    if (val) stats.device[device] = parseInt(val, 10);
+  }
+
+  // Referrer stats
+  const referrerKeys = await kv.list({ prefix: `${REFERRER_PREFIX}${code}:` });
+  for (const key of referrerKeys.keys) {
+    const referrer = key.name.replace(`${REFERRER_PREFIX}${code}:`, '');
+    const val = await kv.get(key.name, 'text');
+    if (val) stats.referrer[referrer] = parseInt(val, 10);
+  }
+
+  return stats;
+}
+
+// --- Index helpers ---
+
+async function getIndex(kv: KVNamespace): Promise<string[]> {
+  const raw = await kv.get(INDEX_KEY, 'text');
+  if (!raw) return [];
+  return JSON.parse(raw) as string[];
+}
+
+async function addToIndex(kv: KVNamespace, code: string): Promise<void> {
+  const index = await getIndex(kv);
+  if (!index.includes(code)) {
+    index.push(code);
+    await kv.put(INDEX_KEY, JSON.stringify(index));
+  }
+}
+
+async function removeFromIndex(kv: KVNamespace, code: string): Promise<void> {
+  const index = await getIndex(kv);
+  const filtered = index.filter((c) => c !== code);
+  await kv.put(INDEX_KEY, JSON.stringify(filtered));
+}

package/src/middleware/auth.ts

@@ -0,0 +1,55 @@
+import type { Context, Next } from 'hono';
+import type { Env } from '../types.js';
+
+/** Public route patterns that do not require authentication. */
+const PUBLIC_PATTERNS = [
+  /^\/health$/,
+  /^\/password\/[^/]+$/,
+  /^\/[^/]+$/, // GET /:slug redirect
+];
+
+/**
+ * Bearer token authentication middleware.
+ * Checks `Authorization: Bearer <token>` header against `env.API_TOKEN`.
+ * Skips auth for public routes (health, redirect, password).
+ */
+export async function authMiddleware(
+  c: Context<{ Bindings: Env }>,
+  next: Next,
+): Promise<undefined | Response> {
+  const path = new URL(c.req.url).pathname;
+  const method = c.req.method;
+
+  // Skip auth for public routes
+  if (method === 'GET') {
+    for (const pattern of PUBLIC_PATTERNS) {
+      if (pattern.test(path)) {
+        await next();
+        return;
+      }
+    }
+  }
+
+  // POST /password/:code is also public
+  if (method === 'POST' && /^\/password\/[^/]+$/.test(path)) {
+    await next();
+    return;
+  }
+
+  const authHeader = c.req.header('Authorization');
+  if (!authHeader) {
+    return c.json({ error: 'Missing Authorization header' }, 401);
+  }
+
+  const parts = authHeader.split(' ');
+  if (parts.length !== 2 || parts[0] !== 'Bearer') {
+    return c.json({ error: 'Invalid Authorization format, expected: Bearer <token>' }, 401);
+  }
+
+  const token = parts[1];
+  if (token !== c.env.API_TOKEN) {
+    return c.json({ error: 'Invalid API token' }, 401);
+  }
+
+  await next();
+}

package/src/routes/health.ts

@@ -0,0 +1,5 @@
+import type { Context } from 'hono';
+
+export function handleHealth(c: Context): Response {
+  return c.json({ status: 'ok', timestamp: new Date().toISOString() });
+}

package/src/routes/import-export.ts

@@ -0,0 +1,49 @@
+import type { ShortUrl } from '@clipr/core';
+import type { Context } from 'hono';
+import { listUrls, putUrl } from '../kv.js';
+import type { Env } from '../types.js';
+
+/** POST /api/import — Bulk import entries from a JSON array. */
+export async function handleImport(c: Context<{ Bindings: Env }>): Promise<Response> {
+  let entries: ShortUrl[];
+  try {
+    entries = await c.req.json<ShortUrl[]>();
+  } catch {
+    return c.json({ error: 'Invalid JSON body, expected an array of ShortUrl entries' }, 400);
+  }
+
+  if (!Array.isArray(entries)) {
+    return c.json({ error: 'Request body must be a JSON array' }, 400);
+  }
+
+  let imported = 0;
+  const errors: string[] = [];
+
+  for (const entry of entries) {
+    if (!entry.slug || !entry.url) {
+      errors.push(`Skipped entry: missing slug or url`);
+      continue;
+    }
+    try {
+      await putUrl(c.env.URLS, entry.slug, {
+        ...entry,
+        createdAt: entry.createdAt || new Date().toISOString(),
+      });
+      imported++;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      errors.push(`Failed to import "${entry.slug}": ${msg}`);
+    }
+  }
+
+  return c.json({ imported, total: entries.length, errors }, 200);
+}
+
+/** GET /api/export — Export all entries as a JSON array. */
+export async function handleExport(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const entries = await listUrls(c.env.URLS);
+
+  return c.json(entries, 200, {
+    'Content-Disposition': 'attachment; filename="clipr-export.json"',
+  });
+}

package/src/routes/links.ts

@@ -0,0 +1,98 @@
+import type { ShortUrl } from '@clipr/core';
+import type { Context } from 'hono';
+import { deleteUrl, getUrl, listUrls, putUrl } from '../kv.js';
+import type { Env } from '../types.js';
+
+/** GET /api/links — List all links with optional filtering. */
+export async function handleListLinks(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const tag = c.req.query('tag');
+  const search = c.req.query('search');
+  const limitStr = c.req.query('limit');
+  const limit = limitStr ? parseInt(limitStr, 10) : undefined;
+
+  let entries = await listUrls(c.env.URLS);
+
+  // Filter by tag
+  if (tag) {
+    entries = entries.filter((e) => e.tags?.includes(tag));
+  }
+
+  // Search across slug, url, description
+  if (search) {
+    const q = search.toLowerCase();
+    entries = entries.filter(
+      (e) =>
+        e.slug.toLowerCase().includes(q) ||
+        e.url.toLowerCase().includes(q) ||
+        e.description?.toLowerCase().includes(q),
+    );
+  }
+
+  // Apply limit
+  if (limit && limit > 0) {
+    entries = entries.slice(0, limit);
+  }
+
+  return c.json(entries);
+}
+
+/** GET /api/links/:code — Get a single link entry. */
+export async function handleGetLink(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const code = c.req.param('code');
+  if (!code) {
+    return c.json({ error: 'Missing code parameter' }, 400);
+  }
+
+  const entry = await getUrl(c.env.URLS, code);
+  if (!entry) {
+    return c.json({ error: `Link "${code}" not found` }, 404);
+  }
+
+  return c.json(entry);
+}
+
+/** PUT /api/links/:code — Update an existing link (partial updates). */
+export async function handleUpdateLink(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const code = c.req.param('code');
+  if (!code) {
+    return c.json({ error: 'Missing code parameter' }, 400);
+  }
+
+  const existing = await getUrl(c.env.URLS, code);
+  if (!existing) {
+    return c.json({ error: `Link "${code}" not found` }, 404);
+  }
+
+  let updates: Partial<ShortUrl>;
+  try {
+    updates = await c.req.json<Partial<ShortUrl>>();
+  } catch {
+    return c.json({ error: 'Invalid JSON body' }, 400);
+  }
+
+  // Merge updates into existing entry (slug and createdAt are immutable)
+  const updated: ShortUrl = {
+    ...existing,
+    ...updates,
+    slug: existing.slug, // never change slug
+    createdAt: existing.createdAt, // never change creation time
+  };
+
+  await putUrl(c.env.URLS, code, updated);
+  return c.json(updated);
+}
+
+/** DELETE /api/links/:code — Delete a link. */
+export async function handleDeleteLink(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const code = c.req.param('code');
+  if (!code) {
+    return c.json({ error: 'Missing code parameter' }, 400);
+  }
+
+  const deleted = await deleteUrl(c.env.URLS, code);
+  if (!deleted) {
+    return c.json({ error: `Link "${code}" not found` }, 404);
+  }
+
+  return c.json({ ok: true, deleted: code });
+}