Merge branch 'preview'

Author: miantiao-me

.env.example

@@ -8,8 +8,12 @@ NUXT_REDIRECT_NO_STORE=false
 NUXT_HOME_URL="https://sink.cool"
 NUXT_CF_ACCOUNT_ID=123456
 NUXT_CF_API_TOKEN=CloudflareAPIToken
+NUXT_CF_ACCESS_TEAM_DOMAIN=""
+NUXT_CF_ACCESS_AUD=""
 NUXT_DATASET=sink
 NUXT_AI_MODEL="@cf/meta/llama-3-8b-instruct"
 NUXT_AI_PROMPT="You are a URL shortening assistant......"
 NUXT_DISABLE_AUTO_BACKUP=false
 NUXT_NOT_FOUND_REDIRECT=/your-own-404-page
+NUXT_WEBHOOK_URL="https://example.com/webhooks/sink"
+NUXT_WEBHOOK_SECRET=""

app/composables/useAuthSession.ts

@@ -0,0 +1,24 @@
+import type { AuthMethod, VerifyResponse } from '@/types'
+import { readonly, useState } from '#imports'
+
+export function useAuthSession() {
+  const authMethod = useState<AuthMethod | null>('auth-method', () => null)
+  const accessEnabled = useState('access-enabled', () => false)
+
+  function setAuthSession(response: VerifyResponse) {
+    authMethod.value = response.authMethod
+    accessEnabled.value = response.accessEnabled
+  }
+
+  function clearAuthSession() {
+    authMethod.value = null
+    accessEnabled.value = false
+  }
+
+  return {
+    authMethod: readonly(authMethod),
+    accessEnabled: readonly(accessEnabled),
+    setAuthSession,
+    clearAuthSession,
+  }
+}

app/types/index.ts

@@ -1,4 +1,5 @@
 export * from '#layers/dashboard/shared/types'
+export * from '#shared/types/auth'
 export * from '#shared/types/link'
 export * from '#shared/types/link-check'
 export * from '#shared/types/traffic'

app/utils/api.ts

@@ -1,5 +1,4 @@
 import type { NitroFetchOptions, NitroFetchRequest } from 'nitropack'
-import { navigateTo } from '#imports'
 import { defu } from 'defu'
 import { useAuthToken } from '@/composables/useAuthToken'
 
@@ -12,14 +11,16 @@ export function useAPI<T = unknown>(api: string, options?: APIOptions): Promise<
 
   const mergedOptions = defu(options || {}, {
     headers: {
-      Authorization: `Bearer ${getToken() || ''}`,
+      'Authorization': `Bearer ${getToken() || ''}`,
+      'X-Requested-With': 'XMLHttpRequest',
     },
   }) as NitroFetchOptions<NitroFetchRequest>
 
   return $fetch<T>(api, mergedOptions).catch((error) => {
     if (error?.status === 401) {
       removeToken()
-      navigateTo('/dashboard/login')
+      if (import.meta.client && window.location.pathname !== '/dashboard/login')
+        window.location.assign('/dashboard/login')
     }
     return Promise.reject(error)
   }) as Promise<T>

docs/api.md

@@ -12,14 +12,16 @@ Visit your Sink instance at `https://your-domain/_docs/scalar` for interactive A
 
 ## Authentication
 
-All API endpoints require authentication via Bearer token in the `Authorization` header:
+All API endpoints accept the site token in the `Authorization` header:
 
 ```http
 Authorization: Bearer YOUR_SITE_TOKEN
 ```
 
 The token is the same as `NUXT_SITE_TOKEN` configured in your environment variables.
 
+When [Cloudflare Access authentication](cloudflare-access.md) is configured, browser requests from an authenticated dashboard session can use the signed Access application token instead. Sink validates the token signature, issuer, audience, and expiration. Clients must not construct or trust `Cf-Access-Jwt-Assertion` themselves; Cloudflare Access supplies the token or authorization cookie.
+
 ## API Endpoints
 
 ### Links

docs/cloudflare-access.md

@@ -0,0 +1,54 @@
+# Cloudflare Access Authentication
+
+Sink can optionally use Cloudflare Access as an alternative to the existing site token. When Access is not configured, authentication behaves exactly as before.
+
+With Access configured, an API request is accepted when either condition is true:
+
+- The request has a valid `NUXT_SITE_TOKEN` bearer token.
+- The request has a valid Cloudflare Access application JWT.
+
+Sink verifies the Access JWT signature, issuer, audience, and expiration against your team's public keys. The presence of an Access header or cookie alone is never trusted.
+
+## Compatibility-first setup
+
+This setup protects the dashboard while keeping public short links and SiteToken API clients unchanged.
+
+1. Create a Cloudflare Access self-hosted application for your Sink hostname.
+2. Configure its application path to cover both `/dashboard` and its child routes.
+3. Do not protect `/api` with Access. Sink authenticates API requests itself using SiteToken or the signed Access application cookie.
+4. In the Access application's advanced cookie settings:
+   - Keep **Cookie Path** disabled so the dashboard cookie is also sent to `/api`.
+   - Set **SameSite** to `Lax` or `Strict` when your deployment does not require cross-site requests.
+5. Add the following Sink environment variables and redeploy:
+
+```ini
+NUXT_CF_ACCESS_TEAM_DOMAIN=https://your-team.cloudflareaccess.com
+NUXT_CF_ACCESS_AUD=your-application-aud-tag
+```
+
+Both variables are required. The team domain should not have a path. The AUD tag is available in the Access application's additional settings.
+
+Short-link paths, static assets, and API documentation remain public at the Cloudflare Access layer. API operations still require Sink authentication. Protect `/_docs` separately if the API schema should not be public.
+
+## Security considerations
+
+In compatibility-first mode, `/api` is not evaluated by the Cloudflare Access proxy on every request. Sink validates the signed application JWT locally. As a result, an Access session revoked by an administrator may remain usable until its JWT expires. Use an appropriately short Access policy or application session duration.
+
+Access uses a browser cookie, so Sink rejects cross-site browser requests authenticated through Access and verifies the `Origin` header for state-changing methods. SiteToken requests are unchanged. Non-browser clients should continue to use `NUXT_SITE_TOKEN`.
+
+Do not expose an alternative deployment hostname with a weak SiteToken. Cloudflare Access on the dashboard does not protect other hostnames that route to the same Worker or Pages project.
+
+## Logout
+
+When the dashboard is authenticated through Access, Sink redirects logout to `/cdn-cgi/access/logout`. Cloudflare revokes the Access session across applications and clears the application cookie.
+
+## Strict setup
+
+For stronger edge enforcement, you can protect both `/dashboard` and `/api` with Access. In this mode, Cloudflare blocks requests before they reach Sink, so a SiteToken-only API client cannot use the protected hostname. Such clients must also use an Access service token or a separate API hostname.
+
+## References
+
+- [Validate Access JWTs](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/)
+- [Access application token](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/application-token/)
+- [Access application paths](https://developers.cloudflare.com/cloudflare-one/access-controls/policies/app-paths/)
+- [Access session management](https://developers.cloudflare.com/cloudflare-one/access-controls/access-settings/session-management/)

docs/configuration.md

@@ -99,6 +99,16 @@ This feature requires:
 
 Backups are stored in R2 with the path `backups/links-{timestamp}.json` and run daily at 00:00 UTC.
 
+## `NUXT_CF_ACCESS_TEAM_DOMAIN`
+
+Optional Cloudflare Access team domain, for example `https://your-team.cloudflareaccess.com`.
+Set this together with `NUXT_CF_ACCESS_AUD` to allow a valid Cloudflare Access session to authenticate API requests as an alternative to `NUXT_SITE_TOKEN`.
+
+## `NUXT_CF_ACCESS_AUD`
+
+Optional Application Audience (AUD) tag from the Cloudflare Access application that protects the dashboard.
+Cloudflare Access authentication is enabled only when both Access variables are configured. Refer to [Cloudflare Access Authentication](cloudflare-access.md) for the required application and cookie settings.
+
 ## `NUXT_SAFE_BROWSING_DOH`
 
 Set to a DNS over HTTPS (DoH) endpoint URL to enable automatic unsafe link detection when creating or editing links. When enabled, Sink queries the DoH service to check if the destination domain is flagged as malicious. If the domain resolves to `0.0.0.0`, the link is automatically marked as unsafe and visitors will see a warning page before being redirected.
@@ -114,3 +124,48 @@ Default is empty (disabled). Users can still manually mark links as unsafe in th
 
 Optional custom redirect target when a slug is not found.
 If this is not set, Sink will fall back to its default 404 page.
+
+## Click Webhooks
+
+Set `NUXT_WEBHOOK_URL` to send a best-effort webhook for each click included in access statistics. An empty URL disables webhooks. Bot clicks skipped by `NUXT_DISABLE_BOT_ACCESS_LOG` are also skipped by webhooks.
+
+`NUXT_WEBHOOK_URL` must use HTTP or HTTPS. HTTPS is strongly recommended in production. `NUXT_WEBHOOK_SECRET` is optional. When configured, it must start with `whsec_`; the suffix is a Base64-encoded HMAC key between 24 and 64 bytes. Generate a 32-byte key with:
+
+```sh
+printf 'whsec_%s\n' "$(openssl rand -base64 32)"
+```
+
+Sink sends a Dub-style payload:
+
+```json
+{
+  "id": "evt_...",
+  "event": "link.clicked",
+  "createdAt": "2026-07-11T12:00:00.000Z",
+  "data": {
+    "click": {
+      "id": "clk_...",
+      "timestamp": "2026-07-11T12:00:00.000Z",
+      "country": "US",
+      "region": "California",
+      "city": "San Francisco",
+      "device": "mobile",
+      "browser": "Mobile Safari",
+      "os": "iOS",
+      "referer": "example.com"
+    },
+    "link": {
+      "id": "link-id",
+      "slug": "example"
+    }
+  }
+}
+```
+
+The click location fields contain the raw Cloudflare country code, region, and city. The device field prefers the parsed device category (such as `mobile`) and falls back to the device model.
+
+Every request includes the Standard Webhooks headers `webhook-id` and `webhook-timestamp`. When a secret is configured, Sink also sends `webhook-signature`. The signature is `v1,<base64>` for HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw-body>`, using the decoded secret suffix as the key. An invalid non-empty secret fails delivery and never falls back to unsigned delivery.
+
+Without `NUXT_WEBHOOK_SECRET`, delivery is unauthenticated and unsigned. This mode is not recommended over untrusted networks; configure a secret whenever the receiver supports signature verification.
+
+Webhook payloads exclude IP addresses, coordinates, full user agents, query parameters, passwords, and destination URLs. Delivery has a 10-second timeout, accepts only 2xx responses, does not follow redirects, and is asynchronous. Failures do not affect redirects and are not retried.

docs/deployment/pages.md

@@ -7,6 +7,8 @@
    - `NUXT_SITE_TOKEN`: Must be at least **8** characters long. This token grants access to your dashboard.
    - `NUXT_CF_ACCOUNT_ID`: Find your [account ID](https://developers.cloudflare.com/fundamentals/setup/find-account-and-zone-ids/).
    - `NUXT_CF_API_TOKEN`: Create a [Cloudflare API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) with at least `Account.Account Analytics` permission. [See reference.](https://developers.cloudflare.com/analytics/analytics-engine/sql-api/#authentication)
+   - (_Optional_) `NUXT_WEBHOOK_URL`: The HTTPS endpoint that enables and receives click webhooks.
+   - (_Optional_) `NUXT_WEBHOOK_SECRET`: A `whsec_`-prefixed Base64 secret. If omitted, delivery is unauthenticated and unsigned, which is not recommended over untrusted networks.
 
 5. Save and deploy the project.
 6. Cancel the deployment, then go to **Settings** -> **Bindings** -> **Add**:
@@ -22,3 +24,7 @@
    - Go to **Settings** -> **Runtime** -> **Compatibility flags** and set the following flags `nodejs_compat`.
 8. Redeploy the project.
 9. To update code, refer to the official GitHub documentation [Syncing a fork branch from the web UI](https://docs.github.com/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork#syncing-a-fork-branch-from-the-web-ui 'GitHub: Syncing a fork').
+
+To optionally protect the dashboard with Cloudflare Zero Trust while keeping short links public, refer to [Cloudflare Access Authentication](../cloudflare-access.md).
+
+Click webhook delivery is best effort and has no retries. See [Click Webhooks](../configuration.md#click-webhooks) for payload, signature, and privacy details.

docs/deployment/workers.md

@@ -14,7 +14,13 @@
    - `NUXT_SITE_TOKEN`: Must be at least **8** characters long. This token grants access to your dashboard.
    - `NUXT_CF_ACCOUNT_ID`: Find your [account ID](https://developers.cloudflare.com/fundamentals/setup/find-account-and-zone-ids/).
    - `NUXT_CF_API_TOKEN`: Create a [Cloudflare API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) with at least `Account.Account Analytics` permission. [See reference.](https://developers.cloudflare.com/analytics/analytics-engine/sql-api/#authentication)
+   - (_Optional_) `NUXT_WEBHOOK_URL`: The HTTPS endpoint that enables and receives click webhooks.
+   - (_Optional_) `NUXT_WEBHOOK_SECRET`: A `whsec_`-prefixed Base64 secret. Generate one with `printf 'whsec_%s\n' "$(openssl rand -base64 32)"` and store it as a secret in the dashboard, not in `wrangler.jsonc`. If omitted, delivery is unauthenticated and unsigned, which is not recommended over untrusted networks.
 
 9. Enable Analytics Engine. In **Workers & Pages**, go to **Account details** in the right panel, locate **Analytics Engine**, and click **Set up** to enable the free tier. Name them `sink` and `ANALYTICS`, or else overwrite it with `NUXT_DATASET` and update your `wrangler.jsonc` accordingly
 10. Redeploy the project.
 11. To update your code, refer to the official GitHub documentation: [Syncing a fork branch from the web UI](https://docs.github.com/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork#syncing-a-fork-branch-from-the-web-ui 'GitHub: Syncing a fork').
+
+To optionally protect the dashboard with Cloudflare Zero Trust while keeping short links public, refer to [Cloudflare Access Authentication](../cloudflare-access.md).
+
+Click webhook delivery is best effort and has no retries. See [Click Webhooks](../configuration.md#click-webhooks) for payload, signature, and privacy details.

layers/dashboard/app/components/dashboard/sidebar/NavUser.vue

@@ -9,6 +9,8 @@ interface User {
 }
 
 const { isMobile } = useSidebar()
+const { getToken, removeToken } = useAuthToken()
+const { authMethod, accessEnabled, clearAuthSession } = useAuthSession()
 
 const hostname = computed<string>(() => {
   if (import.meta.client) {
@@ -24,7 +26,16 @@ const user = computed<User>(() => ({
 }))
 
 function logOut() {
-  localStorage.removeItem('SinkSiteToken')
+  const method = authMethod.value || (getToken() ? 'site-token' : 'cloudflare-access')
+  const shouldLogoutAccess = accessEnabled.value || method === 'cloudflare-access'
+  removeToken()
+  clearAuthSession()
+
+  if (shouldLogoutAccess) {
+    window.location.assign('/cdn-cgi/access/logout')
+    return
+  }
+
   navigateTo('/dashboard/login')
 }
 </script>