@dytsou/shorten-url 2.4.4 → 2.4.5

package/docs/api/openapi.yaml

@@ -3,102 +3,67 @@ info:
   title: Shorten URL Service
   version: 1.0.0
   description: |
-    A modern, fast URL shortener built with Cloudflare Workers and a responsive web interface.
-    - Custom slugs are supported
-    - The homepage is served at /
-    - API is available at / (POST) for shortening URLs
-    - Short URL access is via /{key} (GET)
-    - Custom error pages for 404, security warnings, and redirects
+    URL shortening and first-party Flagship management API for the Shorten URL Worker.
+
+    Shortening requests use `POST /`, regardless of the page path. The production
+    branch may mount the product page at `/shorten`; API routes remain rooted at `/`.
+    Short links resolve through `GET /{key}`. Flag definitions are managed at
+    `/settings/api/*`; these routes require Cloudflare Access. Mutating management
+    requests also require a CSRF token obtained from `/settings/api/csrf`.
+
+    The interactive API reference is published separately from the Worker at the
+    documentation site's `/api/` path.
 
 servers:
   - url: /
 
+tags:
+  - name: Short links
+    description: Create and follow shortened URLs.
+  - name: Flagship management
+    description: Manage the `shorten-routing` flag through the Worker control plane.
+
 paths:
   /:
     post:
+      tags: [Short links]
+      operationId: shortenUrl
       summary: Shorten a URL
-      description: Create a new shortened URL, optionally with a custom slug.
+      description: Create a short URL, optionally with a custom slug.
+      security:
+        - CloudflareAccessJwt: []
+          CloudflareAccessUserEmail: []
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: object
-              required:
-                - url
-              properties:
-                url:
-                  type: string
-                  format: uri
-                  description: The URL to shorten
-                  example: https://www.example.com/very/long/url/path
-                custom_slug:
-                  type: string
-                  pattern: '^[a-zA-Z0-9\-_]+$'
-                  maxLength: 50
-                  description: Optional custom slug for the short URL
-                  example: my-custom-link
+              $ref: "#/components/schemas/ShortenRequest"
       responses:
         "201":
-          description: URL successfully shortened
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  short_url:
-                    type: string
-                    format: uri
-                    example: https://your-worker-domain.example/abc123
+          $ref: "#/components/responses/ShortenCreated"
         "400":
-          description: Bad request
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    type: integer
-                    example: 400
-                  message:
-                    type: string
-                    example: Invalid URL format
+          $ref: "#/components/responses/BadRequest"
         "403":
-          description: Cloudflare Access headers are missing
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorResponse"
+          $ref: "#/components/responses/AccessDenied"
         "404":
-          description: Invalid API path
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorResponse"
+          $ref: "#/components/responses/NotFound"
         "500":
-          description: Server error
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    type: integer
-                    example: 500
-                  message:
-                    type: string
-                    example: Server error
+          $ref: "#/components/responses/ServerError"
     get:
-      summary: Get homepage
-      description: Fetches the configured URL shortener frontend.
+      tags: [Short links]
+      operationId: getHomepage
+      summary: Get the Shorten URL application
       responses:
         "200":
-          description: Homepage HTML
+          description: Worker-hosted application HTML.
           content:
             text/html:
               schema:
                 type: string
     options:
+      tags: [Short links]
+      operationId: preflightHomepage
       summary: Handle CORS preflight
       responses:
         "204":
@@ -106,59 +71,454 @@ paths:
 
   /{key}:
     get:
-      summary: Access shortened URL
-      description: Redirect to the original URL
+      tags: [Short links]
+      operationId: followShortUrl
+      summary: Follow a shortened URL
       parameters:
         - in: path
           name: key
           required: true
+          description: Short URL key.
           schema:
             type: string
-          description: The short URL key
           example: abc123
       responses:
         "302":
-          description: Redirect to original URL
+          description: Redirect to the stored destination.
           headers:
             Location:
+              description: Destination URL.
               schema:
                 type: string
                 format: uri
         "404":
-          description: Short URL not found
+          description: Short URL was not found.
           content:
             text/html:
               schema:
                 type: string
 
+  /settings/api/csrf:
+    get:
+      tags: [Flagship management]
+      operationId: getSettingsCsrfToken
+      summary: Get a CSRF token for management writes
+      description: |
+        Requires Cloudflare Access authentication. The token is scoped to the request
+        origin and authenticated user's email. Use it in the `X-CSRF-Token` header
+        on each management POST or PUT request.
+      security:
+        - CloudflareAccessJwt: []
+          CloudflareAccessUserEmail: []
+      responses:
+        "200":
+          description: CSRF token created.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CsrfTokenResponse"
+        "403":
+          $ref: "#/components/responses/AccessDenied"
+        "503":
+          $ref: "#/components/responses/SettingsUnavailable"
+
+  /settings/api/flags:
+    get:
+      tags: [Flagship management]
+      operationId: listShorteningFlags
+      summary: Read the managed shortening flag
+      description: Returns the `shorten-routing` flag when it exists.
+      security:
+        - CloudflareAccessJwt: []
+          CloudflareAccessUserEmail: []
+      responses:
+        "200":
+          description: Managed flag list.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FlagListResponse"
+        "403":
+          $ref: "#/components/responses/AccessDenied"
+        "502":
+          $ref: "#/components/responses/FlagshipError"
+
+  /settings/api/flag:
+    post:
+      tags: [Flagship management]
+      operationId: createShorteningFlag
+      summary: Create the shortening flag
+      description: |
+        Creates the `shorten-routing` flag. Send the same-origin `Origin` header
+        (or a same-origin `Referer` when `Origin` is absent) and the CSRF token
+        returned by `GET /settings/api/csrf`.
+      security:
+        - CloudflareAccessJwt: []
+          CloudflareAccessUserEmail: []
+      parameters:
+        - $ref: "#/components/parameters/CsrfToken"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/FlagDefinition"
+      responses:
+        "201":
+          description: Flag created.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FlagResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/AccessDenied"
+        "413":
+          $ref: "#/components/responses/PayloadTooLarge"
+        "415":
+          $ref: "#/components/responses/JsonRequired"
+        "502":
+          $ref: "#/components/responses/FlagshipError"
+
+  /settings/api/flag/shorten-routing:
+    put:
+      tags: [Flagship management]
+      operationId: saveShorteningFlag
+      summary: Save a shortening flag draft
+      description: |
+        Saves the draft using optimistic concurrency. `expectedUpdatedAt` must
+        match the currently saved version. Include the same-origin `Origin`
+        header (or a same-origin `Referer` when absent) and the CSRF token.
+      security:
+        - CloudflareAccessJwt: []
+          CloudflareAccessUserEmail: []
+      parameters:
+        - $ref: "#/components/parameters/CsrfToken"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SaveFlagRequest"
+      responses:
+        "200":
+          description: Draft saved.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FlagResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "403":
+          $ref: "#/components/responses/AccessDenied"
+        "409":
+          $ref: "#/components/responses/VersionConflict"
+        "413":
+          $ref: "#/components/responses/PayloadTooLarge"
+        "415":
+          $ref: "#/components/responses/JsonRequired"
+        "502":
+          $ref: "#/components/responses/FlagshipError"
+
+  /settings/api/flag/shorten-routing/publish:
+    post:
+      tags: [Flagship management]
+      operationId: publishShorteningFlag
+      summary: Publish the saved shortening flag
+      description: |
+        Publishes the current saved version. The required `expectedUpdatedAt`
+        prevents publishing a draft that changed after it was loaded. Include the
+        same-origin `Origin` header (or a same-origin `Referer` when absent) and
+        the CSRF token.
+      security:
+        - CloudflareAccessJwt: []
+          CloudflareAccessUserEmail: []
+      parameters:
+        - $ref: "#/components/parameters/CsrfToken"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PublishFlagRequest"
+      responses:
+        "200":
+          description: Flag published.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FlagResponse"
+        "403":
+          $ref: "#/components/responses/AccessDenied"
+        "409":
+          $ref: "#/components/responses/VersionConflict"
+        "413":
+          $ref: "#/components/responses/PayloadTooLarge"
+        "415":
+          $ref: "#/components/responses/JsonRequired"
+        "502":
+          $ref: "#/components/responses/FlagshipError"
+
 components:
+  securitySchemes:
+    CloudflareAccessJwt:
+      type: apiKey
+      in: header
+      name: Cf-Access-Jwt-Assertion
+      description: Cloudflare Access JWT assertion supplied by the Access-protected hostname.
+    CloudflareAccessUserEmail:
+      type: apiKey
+      in: header
+      name: Cf-Access-Authenticated-User-Email
+      description: Authenticated user's email supplied by Cloudflare Access.
+  parameters:
+    CsrfToken:
+      in: header
+      name: X-CSRF-Token
+      required: true
+      description: Token returned by `GET /settings/api/csrf`.
+      schema:
+        type: string
   schemas:
     ShortenRequest:
       type: object
-      required:
-        - url
+      required: [url]
       properties:
         url:
           type: string
           format: uri
-          description: The URL to shorten
+          description: Destination URL to shorten.
+          example: https://www.example.com/very/long/url/path
         custom_slug:
           type: string
-          pattern: '^[a-zA-Z0-9\-_]+$'
+          pattern: "^[A-Za-z0-9_-]{1,50}$"
           maxLength: 50
-          description: Optional custom slug
-
+          description: Optional custom slug; omitted or blank values use a generated key.
+          example: spring-launch
     ShortenResponse:
       type: object
+      required: [short_url]
       properties:
         short_url:
           type: string
           format: uri
-
+          example: https://your-worker-domain.example/abc123
+    CsrfTokenResponse:
+      type: object
+      required: [csrfToken]
+      properties:
+        csrfToken:
+          type: string
+          description: Origin- and user-scoped token required for management writes.
+    FlagDefinition:
+      type: object
+      description: Draft definition for the single `shorten-routing` flag.
+      required: [enabled, defaultVariant, variants]
+      properties:
+        key:
+          type: string
+          const: shorten-routing
+        description:
+          type: string
+          maxLength: 512
+        enabled:
+          type: boolean
+        defaultVariant:
+          type: string
+          description: Key of the default destination variant.
+        variants:
+          type: array
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/FlagVariant"
+        rules:
+          type: array
+          items:
+            $ref: "#/components/schemas/TargetingRule"
+    FlagVariant:
+      type: object
+      required: [key, value]
+      properties:
+        key:
+          type: string
+          pattern: "^[A-Za-z0-9_-]{1,64}$"
+        value:
+          type: object
+          required: [url]
+          properties:
+            url:
+              type: string
+              format: uri
+              description: Safe HTTP or HTTPS destination for this variant.
+    TargetingRule:
+      type: object
+      required: [priority, variant]
+      properties:
+        priority:
+          type: integer
+          minimum: 1
+          description: Unique rule priority; lower numbers are evaluated first.
+        variant:
+          type: string
+          description: Variant key to serve when this rule matches.
+        conditions:
+          type: array
+          maxItems: 16
+          description: All conditions must match; an empty list matches every visitor.
+          items:
+            $ref: "#/components/schemas/TargetingCondition"
+        rolloutPercentage:
+          type: number
+          minimum: 0
+          maximum: 100
+          multipleOf: 0.01
+          description: Optional stable per-visitor rollout percentage from 0 to 100.
+    TargetingCondition:
+      type: object
+      required: [attribute, operator, value]
+      properties:
+        attribute:
+          type: string
+          enum:
+            - country
+            - regionCode
+            - continent
+            - timezone
+            - language
+            - utmSource
+            - utmMedium
+            - utmCampaign
+        operator:
+          type: string
+          enum:
+            - equals
+            - not_equals
+            - contains
+            - starts_with
+            - ends_with
+            - in
+            - not_in
+        value:
+          oneOf:
+            - type: string
+              minLength: 1
+              maxLength: 256
+            - type: array
+              minItems: 1
+              maxItems: 50
+              items:
+                type: string
+                minLength: 1
+                maxLength: 256
+          description: Use a string except with `in` and `not_in`, which require a string list. Country values must be two-letter codes.
+    SaveFlagRequest:
+      allOf:
+        - $ref: "#/components/schemas/FlagDefinition"
+        - type: object
+          required: [expectedUpdatedAt]
+          properties:
+            expectedUpdatedAt:
+              type: string
+              minLength: 1
+              description: Version identifier returned with the currently saved flag.
+    PublishFlagRequest:
+      type: object
+      required: [expectedUpdatedAt]
+      properties:
+        expectedUpdatedAt:
+          type: string
+          minLength: 1
+          description: Version identifier returned with the currently saved flag.
+    SavedFlag:
+      allOf:
+        - $ref: "#/components/schemas/FlagDefinition"
+        - type: object
+          required: [key, updatedAt]
+          properties:
+            updatedAt:
+              type: [string, "null"]
+              description: Timestamp/version for optimistic concurrency.
+    FlagResponse:
+      type: object
+      required: [flag]
+      properties:
+        flag:
+          $ref: "#/components/schemas/SavedFlag"
+    FlagListResponse:
+      type: object
+      required: [flags]
+      properties:
+        flags:
+          type: array
+          items:
+            $ref: "#/components/schemas/SavedFlag"
     ErrorResponse:
       type: object
+      required: [status, message]
       properties:
         status:
           type: integer
         message:
           type: string
+  responses:
+    ShortenCreated:
+      description: URL successfully shortened.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ShortenResponse"
+    BadRequest:
+      description: Invalid request body or flag definition.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    AccessDenied:
+      description: Cloudflare Access authentication, origin validation, or CSRF validation failed.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    NotFound:
+      description: API route was not found.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    ServerError:
+      description: Shortening request failed.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    SettingsUnavailable:
+      description: Settings API is not configured.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    FlagshipError:
+      description: Flagship provider request failed.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    VersionConflict:
+      description: Expected version is missing or no longer current.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    PayloadTooLarge:
+      description: Request body exceeds the maximum allowed size.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+    JsonRequired:
+      description: Management writes require an application/json request body.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"

package/docs/flagship.md

@@ -0,0 +1,58 @@
+# Flagship shortening controls
+
+The two maintained Worker entrypoints use the first-party Cloudflare Flagship
+binding when it is provisioned as `env.FLAGS`. The binding is intentionally
+behind a typed adapter in `src/lib/flagship.js`: if the binding is absent, its
+response is malformed, or evaluation reports an error, requests use the
+existing shortening page and redirect behavior.
+
+## Provisioning
+
+1. Create a Flagship app and replace the placeholder in the `[[flagship]]`
+   block in `wrangler.toml` (see `wrangler.toml.example`).
+2. Create the JSON flag `shorten-routing`. Variations must be objects with a
+   single `url` field. Rules can target the `country` attribute with `in` and
+   two-letter country codes, apply a percentage rollout, or combine both.
+   Percentage rules use Flagship's `targetingKey` bucketing attribute. The
+   Worker assigns an opaque first-party cookie so a browser keeps its canary
+   assignment between visits. Set the control variation as the default; users
+   outside a rollout receive its destination.
+   A single 5% rule gives a 5% canary and sends the rest to the default. When
+   splitting one audience across multiple variants, use cumulative thresholds:
+   30%, 70%, and 100% produce a 30/40/30 split. Repeat the same audience
+   conditions and bucketing attribute on those rules.
+3. Configure the protected settings API secrets/variables:
+   `CLOUDFLARE_ACCOUNT_ID`, `FLAGSHIP_APP_ID`, `FLAGSHIP_API_TOKEN`,
+   `FLAGSHIP_CSRF_SECRET`, `CF_ACCESS_ISSUER`, and `CF_ACCESS_AUDIENCE`.
+   `CF_ACCESS_JWKS_URL` is optional when the standard Access certificate URL
+   is available.
+4. Deploy behind the same Cloudflare Access application that protects
+   `/shorten`. Operators open `/` in the deployed Worker and switch to the Flagship tab; there is
+   no standalone settings page route.
+
+When the built `frontend/` app is deployed to GitHub Pages or another static
+host, set its `shorten-url-worker-origin` meta tag to the public Worker origin.
+The frontend tabs and settings API requests use that origin. Leave the tag
+empty when the Worker serves the page so the current origin remains the
+fallback. The origin is public and must also match `frontend.workerOrigin` in
+the local config example; do not put any Access, Flagship, or CSRF secret in
+the HTML or frontend config.
+
+The settings API uses the documented Cloudflare Flagship management API for
+country targeting, percentage rollouts, listing, creating, updating, and
+enabling the published flag. The API's full-replacement update is the atomic
+publication boundary; there is no second Worker-owned draft store. API tokens
+stay server-side. Writes require
+a verified Access JWT, JSON requests from the Worker or configured frontend
+origin, and an HMAC CSRF token returned by the settings API. A stale
+`updated_at` value is rejected with
+`409` instead of overwriting another operator's edit.
+
+The installed repository tooling does not provide a `Flagship` TypeScript
+declaration or management client package, so the adapter uses the documented
+binding method (`getObjectDetails`) and an explicit JSDoc interface. This
+keeps local Vitest runs runnable without inventing a second KV-backed flag
+authority. Until the official binding is configured, settings management
+returns a non-sensitive `503` and visitor traffic falls back safely. Mutations
+accept the Worker origin or the configured origin that hosts `frontend/`, and
+the Worker returns credential-compatible CORS headers for that frontend.