@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/recipes/middleware/tests/requests.json

@@ -0,0 +1,528 @@
+[
+  {
+    "path": "/api/private",
+    "status": 401,
+    "expectHeaders": {
+      "www-authenticate": "Bearer realm=\"cookbook\""
+    }
+  },
+  {
+    "path": "/api/private",
+    "status": 401,
+    "headers": {
+      "authorization": "Bearer wrong-token"
+    }
+  },
+  {
+    "path": "/api/private",
+    "status": 200,
+    "headers": {
+      "authorization": "Bearer cookbook-token"
+    },
+    "expectBody": "{\"private\":true}"
+  },
+  {
+    "path": "/api/private",
+    "status": 200,
+    "method": "HEAD",
+    "headers": {
+      "authorization": "Bearer cookbook-token"
+    },
+    "expectBody": ""
+  },
+  {
+    "path": "/admin/panel",
+    "status": 401,
+    "expectHeaders": {
+      "www-authenticate": "Basic realm=\"cookbook\", charset=\"UTF-8\""
+    }
+  },
+  {
+    "path": "/admin/panel",
+    "status": 401,
+    "headers": {
+      "authorization": "Basic YWRtaW46d3Jvbmc="
+    }
+  },
+  {
+    "path": "/admin/panel",
+    "status": 200,
+    "headers": {
+      "authorization": "Basic YWRtaW46Y29va2Jvb2stcGFzc3dvcmQ="
+    },
+    "expectBody": "Admin panel"
+  },
+  {
+    "path": "/admin/panel",
+    "status": 200,
+    "method": "HEAD",
+    "headers": {
+      "authorization": "Basic YWRtaW46Y29va2Jvb2stcGFzc3dvcmQ="
+    },
+    "expectBody": ""
+  },
+  {
+    "path": "/cors/data",
+    "status": 204,
+    "method": "OPTIONS",
+    "headers": {
+      "origin": "https://app.example.com",
+      "access-control-request-method": "GET"
+    },
+    "expectBody": "",
+    "expectHeaders": {
+      "access-control-allow-origin": "https://app.example.com",
+      "access-control-allow-methods": "GET, HEAD, OPTIONS",
+      "vary": "origin"
+    }
+  },
+  {
+    "path": "/cors/data",
+    "status": 204,
+    "method": "OPTIONS",
+    "headers": {
+      "origin": "https://evil.example.net"
+    },
+    "expectBody": "",
+    "expectHeaders": {
+      "vary": "origin"
+    }
+  },
+  {
+    "path": "/cors/data",
+    "status": 200,
+    "headers": {
+      "origin": "https://admin.example.com"
+    },
+    "expectBody": "{\"shared\":true}",
+    "expectHeaders": {
+      "access-control-allow-origin": "https://admin.example.com"
+    }
+  },
+  {
+    "path": "/cors/data",
+    "status": 200,
+    "expectBody": "{\"shared\":true}",
+    "expectHeaders": {
+      "vary": "origin"
+    }
+  },
+  {
+    "path": "/cors/data",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": "",
+    "expectHeaders": {
+      "vary": "origin"
+    }
+  },
+  {
+    "path": "/traced",
+    "status": 200,
+    "headers": {
+      "x-correlation-id": "trace-123"
+    },
+    "expectBody": "Traced",
+    "expectHeaders": {
+      "x-correlation-id": "trace-123"
+    }
+  },
+  {
+    "path": "/traced",
+    "status": 200,
+    "headers": {
+      "x-correlation-id": "not valid!"
+    },
+    "expectBody": "Traced"
+  },
+  {
+    "path": "/traced",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/maintenance",
+    "status": 503,
+    "expectBody": "Down for maintenance\n",
+    "expectHeaders": {
+      "retry-after": "120"
+    }
+  },
+  {
+    "path": "/maintenance",
+    "status": 200,
+    "method": "HEAD",
+    "headers": {
+      "x-maintenance-bypass": "let-me-in"
+    },
+    "expectBody": ""
+  },
+  {
+    "path": "/maintenance",
+    "status": 200,
+    "headers": {
+      "x-maintenance-bypass": "let-me-in"
+    },
+    "expectBody": "Still here"
+  },
+  {
+    "path": "/fragile",
+    "status": 200,
+    "headers": {
+      "x-correlation-id": "r-1"
+    },
+    "expectBody": "{\"healthy\":true}",
+    "expectHeaders": {
+      "x-correlation-id": "r-1"
+    }
+  },
+  {
+    "path": "/fragile?fail=true",
+    "status": 500,
+    "headers": {
+      "x-correlation-id": "r-2"
+    },
+    "expectBody": "{\"error\":\"Temporarily unavailable\",\"correlationId\":\"r-2\"}",
+    "expectHeaders": {
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/fragile",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/fragile?fail=true",
+    "status": 500,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/fragile?fail=perhaps",
+    "status": 400
+  },
+  {
+    "path": "/api/items",
+    "status": 200,
+    "expectBody": "{\"ok\":true,\"data\":[{\"id\":1,\"name\":\"first\"},{\"id\":2,\"name\":\"second\"}],\"meta\":{\"route\":\"/api/items\",\"count\":2}}"
+  },
+  {
+    "path": "/api/items",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/negotiated",
+    "status": 200,
+    "expectBody": "{\"service\":\"cookbook\",\"state\":\"ok\"}",
+    "expectHeaders": {
+      "vary": "accept"
+    }
+  },
+  {
+    "path": "/negotiated",
+    "status": 200,
+    "headers": {
+      "accept": "application/json"
+    },
+    "expectBody": "{\"service\":\"cookbook\",\"state\":\"ok\"}"
+  },
+  {
+    "path": "/negotiated",
+    "status": 200,
+    "headers": {
+      "accept": "text/plain, application/json;q=0.5"
+    },
+    "expectBody": "service: cookbook\nstate: ok\n",
+    "expectHeaders": {
+      "content-type": "text/plain; charset=utf-8"
+    }
+  },
+  {
+    "path": "/negotiated",
+    "status": 406,
+    "headers": {
+      "accept": "image/png"
+    }
+  },
+  {
+    "path": "/negotiated",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "expectBody": "{\"method\":\"GET\",\"tunneled\":false}"
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "POST",
+    "expectBody": "{\"method\":\"POST\",\"tunneled\":false}"
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "POST",
+    "headers": {
+      "x-http-method-override": "delete"
+    },
+    "expectBody": "{\"method\":\"DELETE\",\"tunneled\":true}"
+  },
+  {
+    "path": "/resource",
+    "status": 405,
+    "method": "POST",
+    "headers": {
+      "x-http-method-override": "TRACE"
+    },
+    "expectHeaders": {
+      "allow": "PUT, PATCH, DELETE"
+    }
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "PUT",
+    "expectBody": "{\"method\":\"PUT\",\"tunneled\":false}"
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "PATCH",
+    "expectBody": "{\"method\":\"PATCH\",\"tunneled\":false}"
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "DELETE",
+    "expectBody": "{\"method\":\"DELETE\",\"tunneled\":false}"
+  },
+  {
+    "path": "/versioned",
+    "status": 200,
+    "expectBody": "{\"version\":3,\"items\":[\"alpha\",\"beta\"]}",
+    "expectHeaders": {
+      "etag": "W/\"b4124e8a\"",
+      "cache-control": "public, max-age=60"
+    }
+  },
+  {
+    "path": "/versioned",
+    "status": 304,
+    "headers": {
+      "if-none-match": "W/\"b4124e8a\""
+    },
+    "expectBody": "",
+    "expectHeaders": {
+      "etag": "W/\"b4124e8a\""
+    }
+  },
+  {
+    "path": "/versioned",
+    "status": 200,
+    "headers": {
+      "if-none-match": "W/\"stale\""
+    },
+    "expectHeaders": {
+      "etag": "W/\"b4124e8a\""
+    }
+  },
+  {
+    "path": "/versioned",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": "",
+    "expectHeaders": {
+      "etag": "W/\"b4124e8a\""
+    }
+  },
+  {
+    "path": "/experiment",
+    "status": 302,
+    "headers": {
+      "cookie": "bucket=a"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/landing",
+      "vary": "cookie"
+    }
+  },
+  {
+    "path": "/experiment",
+    "status": 302,
+    "headers": {
+      "cookie": "theme=light; bucket=b"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/landing-b",
+      "vary": "cookie"
+    }
+  },
+  {
+    "path": "/experiment",
+    "status": 302,
+    "expectHeaders": {
+      "vary": "cookie"
+    }
+  },
+  {
+    "path": "/experiment",
+    "status": 302,
+    "method": "HEAD",
+    "headers": {
+      "cookie": "bucket=a"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/landing"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "expectHeaders": {
+      "location": "https://example.com/en/welcome",
+      "vary": "accept-language"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "headers": {
+      "accept-language": "de-DE,de;q=0.9,en;q=0.8"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/de/welcome"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "headers": {
+      "accept-language": "fr-CA"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/fr/welcome"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "headers": {
+      "accept-language": "ja"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/en/welcome"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "method": "HEAD",
+    "headers": {
+      "accept-language": "de"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/de/welcome"
+    }
+  },
+  {
+    "path": "/downloads/report",
+    "status": 403
+  },
+  {
+    "path": "/downloads/report",
+    "status": 403,
+    "headers": {
+      "referer": "https://evil.example.net/page"
+    }
+  },
+  {
+    "path": "/downloads/report",
+    "status": 200,
+    "headers": {
+      "referer": "https://www.example.com/docs"
+    },
+    "expectBody": "URLCode guide\n",
+    "expectHeaders": {
+      "content-disposition": "attachment; filename=report.txt"
+    }
+  },
+  {
+    "path": "/downloads/report",
+    "status": 200,
+    "method": "HEAD",
+    "headers": {
+      "referer": "https://example.com/"
+    },
+    "expectBody": ""
+  },
+  {
+    "path": "/profile",
+    "status": 201,
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{\"name\":\"Ada\",\"age\":36}",
+    "expectBody": "{\"welcome\":\"Ada\",\"age\":36}"
+  },
+  {
+    "path": "/profile",
+    "status": 422,
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{\"name\":\"\",\"age\":-1,\"role\":\"x\"}",
+    "expectBody": "{\"errors\":[\"name must be 1-80 characters\",\"age must be an integer from 0 to 150\",\"unknown field role\"]}"
+  },
+  {
+    "path": "/profile",
+    "status": 400,
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "["
+  },
+  {
+    "path": "/profile",
+    "status": 405
+  },
+  {
+    "path": "/inspect?topic=middleware",
+    "status": 200,
+    "expectBody": "Nothing to see"
+  },
+  {
+    "path": "/inspect?topic=middleware",
+    "status": 200,
+    "headers": {
+      "x-debug": "1",
+      "authorization": "Bearer hidden"
+    },
+    "expectHeaders": {
+      "cache-control": "no-store",
+      "content-type": "application/json"
+    }
+  },
+  {
+    "path": "/inspect",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  }
+]

package/recipes/middleware/urlcode.yaml

@@ -0,0 +1,127 @@
+version: "1"
+# Reusable middleware patterns, one route per module. Bindings are literal values
+# here; production projects use {secret: name} with an operator grant instead.
+# Rename or delete the routes you do not need; the modules are independent.
+routes:
+  /api/private:
+    description: Bearer token gate with a constant-time comparison
+    env:
+      API_TOKEN: {value: cookbook-token}
+    middleware:
+      - source: middleware/auth.mjs
+        export: bearer
+    respond: {json: {private: true}}
+  /admin/panel:
+    description: HTTP Basic authentication decoded inside the guest
+    env:
+      ADMIN_USER: {value: admin}
+      ADMIN_PASSWORD: {value: cookbook-password}
+    middleware:
+      - source: middleware/auth.mjs
+        export: basic
+    respond: {text: Admin panel}
+  /cors/data:
+    description: CORS allowlist with preflight handled before the handler
+    methods: [GET, HEAD, OPTIONS]
+    env:
+      ALLOWED_ORIGINS: {value: https://app.example.com https://admin.example.com}
+    middleware:
+      - source: middleware/cors.mjs
+    respond: {json: {shared: true}}
+  /traced:
+    description: Caller correlation id and Server-Timing on every response
+    middleware:
+      - source: middleware/request-id.mjs
+    respond: {text: Traced}
+  /maintenance:
+    description: Kill switch returning 503 unless a bypass header is presented
+    env:
+      MAINTENANCE: {value: "true"}
+      MAINTENANCE_BYPASS: {value: let-me-in}
+    middleware:
+      - source: middleware/maintenance.mjs
+    respond: {text: Still here}
+  /fragile:
+    description: Error boundary turning a thrown exception into a JSON 500
+    parameters:
+      - name: fail
+        in: query
+        schema: {type: boolean, default: false}
+    middleware:
+      - source: middleware/request-id.mjs
+      - source: middleware/errors.mjs
+    function:
+      source: functions/fail.mjs
+      args:
+        fail: {from: query, name: fail}
+  /api/items:
+    description: JSON envelope around a function response
+    middleware:
+      - source: middleware/envelope.mjs
+    function: {source: functions/items.mjs}
+  /negotiated:
+    description: Accept-driven JSON or plain-text representation, 406 otherwise
+    middleware:
+      - source: middleware/negotiate.mjs
+    function: {source: functions/status.mjs}
+  /resource:
+    description: Method override tunneling PUT, PATCH or DELETE through POST
+    methods: [GET, HEAD, POST, PUT, PATCH, DELETE]
+    middleware:
+      - source: middleware/methods.mjs
+        export: override
+    function: {source: functions/resource.mjs}
+  /versioned:
+    description: Weak ETag and 304 for function output
+    middleware:
+      - source: middleware/etag.mjs
+    function: {source: functions/catalog.mjs}
+  /experiment:
+    description: Sticky A/B bucket cookie choosing between two destinations
+    env:
+      VARIANT_URL: {value: https://example.com/landing-b}
+    middleware:
+      - source: middleware/bucket.mjs
+    redirect: {url: https://example.com/landing}
+  /welcome:
+    description: Accept-Language redirect to a localized destination
+    env:
+      LOCALES: {value: en de fr}
+      SITE: {value: https://example.com}
+    middleware:
+      - source: middleware/locale.mjs
+    redirect: {url: https://example.com/en/welcome}
+  /downloads/report:
+    description: Referer allowlist in front of a native download
+    env:
+      ALLOWED_REFERERS: {value: example.com www.example.com}
+    middleware:
+      - source: middleware/referer.mjs
+    download:
+      file: public/guide.txt
+      filename: report.txt
+      contentType: text/plain
+      cacheControl: no-store
+  /profile:
+    description: Body validated once in middleware, parsed object passed through state
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 4096
+        contentTypes: [application/json]
+        format: json
+    middleware:
+      - source: middleware/body.mjs
+    function: {source: functions/profile.mjs}
+  /inspect:
+    description: Authoring aid echoing inputs, args and redacted headers on demand
+    parameters:
+      - name: topic
+        in: query
+        schema: {type: string, default: routing}
+    env:
+      DEBUG: {value: "true"}
+    middleware:
+      - source: middleware/debug.mjs
+    respond: {text: Nothing to see}

package/recipes/protected-download/README.md

@@ -0,0 +1,22 @@
+# Protected download
+
+`/downloads/report` serves `files/report.txt` as an attachment, but only after
+the operator-installed `auth` extension authorizes the request (`auth: true`,
+the short form of `policies.extensions.auth`). The file is
+served natively: no guest code runs, and the response is forced to `no-store`.
+
+Like the `authenticated-json-api` recipe, this project declares the extension
+and needs an operator host file outside the project plus the canonical origin
+for every command:
+
+```sh
+urlcode validate --local --project . --host-file /operator/host.mjs --origin https://files.example.com
+urlcode test --project . --host-file /operator/host.mjs --origin https://files.example.com
+urlcode audit --project . --expect-routes 1 --host-file /operator/host.mjs --origin https://files.example.com
+```
+
+Use the host file from the `authenticated-json-api` README with the config
+schema accepting `realm: downloads`; the bundled fixtures expect the demo token
+`demo-token`. A real deployment registers `urlcode-auth` instead. Replace
+`files/report.txt` with the real attachment and adjust `filename` and
+`contentType`. Cloudflare refuses extensions.

package/recipes/protected-download/files/report.txt

@@ -0,0 +1 @@
+Quarterly report (placeholder). Replace this file with the real attachment.