Tài liệu hướng dẫn

Giới thiệu

ShortYourLinks là công cụ rút gọn liên kết bảo mật cao, tập trung vào quyền riêng tư và chống bot. Dữ liệu của bạn sẽ tự động biến mất sau 30 ngày để đảm bảo an toàn.

Sử dụng giao diện Web

1. 1. Dán link dài vào ô nhập liệu ở trang chủ.
2. 2. Xác thực Cloudflare Turnstile (bắt buộc để mở khóa nút rút gọn).
3. 3. Nhấn nút rút gọn và nhận kết quả.
4. 4. Bạn có thể quản lý link tại mục "Manage" (Liên kết với địa chỉ IP mạng của bạn).

Tài liệu API (Public)

API của chúng tôi cho phép bạn tạo và quản lý link từ ứng dụng của riêng bạn (Discord Bot, Telegram Bot, script automation...).

POST https://shortyourlinks.prmgvyt.xyz/api.php

Headers bắt buộc

Content-Type: application/json
X-CSRF-Token:   <csrf_token>
X-Access-Token: <access_token>
X-Signature:    <hmac_sha256_signature>

Cấu trúc yêu cầu (JSON):

{
  "action": "create",
  "url": "https://example.com/your-very-long-link-here",
  "cf-turnstile-response": "<turnstile_token>"
}

Phản hồi thành công 200 OK

{
  "status": "success",
  "message": "Link created successfully.",
  "code": "aB12zX",
  "short_url": "https://shortyourlinks.prmgvyt.xyz/aB12zX",
  "expires": "30 days"
}

Kiểm tra thống kê (Analytics)

Lấy số lượt click và ngày tạo của một mã link ngắn.

Yêu cầu

{
  "action": "analytics",
  "code": "aB12zX",
  "cf-turnstile-response": "<turnstile_token>"
}

Phản hồi 200 OK

{
  "status": "success",
  "data": {
    "long_url": "https://example.com/...",
    "created_at": "2026-04-15 08:30:00",
    "clicks": 142
  }
}

Bảo mật API

1. Cơ chế One-Time Token

Mỗi lần trang được tải, server sinh một bộ token mới (csrf, access_token, signature). Token cũ bị vô hiệu hóa ngay sau khi sử dụng thành công. Điều này ngăn chặn tấn công Replay Attack.

2. Xác thực chữ ký HMAC-SHA256

Server tính toán lại chữ ký từ SESSION và so sánh với header gửi lên. Nếu không khớp → từ chối ngay lập tức.

// Signature formula (server-side)
 $expected = hash_hmac("sha256", $session_csrf . $session_token, $secret);
if (!hash_equals($expected, $submitted_sign)) {
    // → Redirect to 404 (Silent Failure)
}

3. Cloudflare Turnstile

Mọi request đều phải kèm token Turnstile hợp lệ. Server xác minh với API của Cloudflare trước khi xử lý — bot và script tự động bị chặn.

4. Ẩn lỗi (Silent Failure)

Bất kỳ hành động nào vi phạm (Sai token, Rate limit, URL cấm) đều sẽ bị đẩy về trang 404 Not Found. Điều này khiến bot không thể biết được mình bị chặn vì lỗi gì, ngăn chặn tấn công dò tìm lỗ hổng (Enumeration).

Best Practices

✅ Nên làm

❌ Không nên làm

Ví dụ JavaScript (đúng cách)

async function shortenURL(longUrl) {
  // 1. Đọc token từ hidden input (KHÔNG hardcode)
  const csrf      = document.getElementById('_csrf').value;
  const token     = document.getElementById('_token').value;
  const signature = document.getElementById('_sign').value;
  const tsToken   = document.querySelector('[name="cf-turnstile-response"]').value;

  // 2. Validate scheme trước khi gửi
  const url = new URL(longUrl);
  if (!['http:', 'https:'].includes(url.protocol)) {
    throw new Error('Invalid URL scheme');
  }

  // 3. Gọi API
  const res = await fetch('/api.php', {
    method: 'POST',
    headers: {
      'Content-Type':   'application/json',
      'X-CSRF-Token':   csrf,
      'X-Access-Token': token,
      'X-Signature':    signature,
    },
    body: JSON.stringify({
      action: 'create',
      url: longUrl,
      'cf-turnstile-response': tsToken,
    }),
  });

  // Nếu bị 404, có thể do vi phạm bảo mật hoặc lỗi hệ thống
  if (!res.ok) throw new Error('Request failed or blocked');

  const data = await res.json();

  // 4. Kiểm tra status trước khi dùng kết quả
  if (data.status !== 'success') {
    throw new Error(data.message);
  }

  // 5. Đợi 5 giây (activation delay)
  await new Promise(r => setTimeout(r, 5000));

  return data.short_url;
}

Xử lý lỗi

Giới hạn & Bảo mật

• 🌐 Web/API: Tối đa 50 link / 7 ngày mỗi IP.
• ⏱️ Tự động xóa: Mọi link đều hết hạn sau 30 ngày.
• 🤖 Bot detection: Cloudflare Turnstile + HMAC signature + Silent Failure tự động chặn script tự động