@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/examples/cookbook/routes/middleware.yaml

@@ -0,0 +1,126 @@
+version: "1"
+# Reusable middleware patterns. Each module lives in middleware/ and is documented
+# in docs/MIDDLEWARE-EXAMPLES.md. Bindings are literal values here; production
+# projects use {secret: name} with an operator grant instead.
+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, in the short form (a module path expands to source)
+    middleware: [middleware/envelope.mjs]
+    function: 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/examples/cookbook/tests/requests.json

@@ -250,5 +250,531 @@
   {
     "path": "/sitemap.xml",
     "status": 404
+  },
+  {
+    "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/examples/cookbook/urlcode.yaml

@@ -6,6 +6,7 @@ includes:
   - routes/responses.yaml
   - routes/files.yaml
   - routes/policies.yaml
+  - routes/middleware.yaml
 routes: {}
 # Site conventions: each key generates one native route (see docs/SITE.md).
 # sitemap is left out here because the cookbook audit runs without --origin.

package/examples/egress/README.md

@@ -0,0 +1,22 @@
+# Operator-granted egress example
+
+This executable schema example uses reserved example destinations. Replace them
+with HTTPS endpoints you own before attempting requests. No test or authoring
+inspection needs network access.
+
+Generate the requested permission document with the CLI `permissions` command,
+review it and save it **outside this project**, then pass it with `--policy` when
+starting the runtime. The generated hash pins these routes and function sources;
+regenerate and review grants after changing declarations. Keep proxy and signal
+origin grants separate. An origin grant authorizes the declared destination and
+its explicit path/query/header behavior; it is not a guest fetch capability.
+
+`GET /proxy/hello?page=2` proxies to the declared items endpoint. Incoming cookies,
+Authorization and unlisted query values are not forwarded. `GET /event` returns
+its native response and schedules a best-effort webhook with route pattern,
+method and status only. HEAD and generated readiness probes do not emit signals.
+There is no retry, queue or delivery guarantee.
+
+See [egress contract](../../docs/EGRESS.md). Integration tests execute this example
+with trusted fake transport and public-address fixtures, never by allowing private
+network destinations in production.

package/examples/egress/example.yaml

@@ -0,0 +1,19 @@
+id: egress
+description: A bounded HTTPS proxy route and a route with a best-effort signal, both needing revision-pinned operator egress grants.
+tags: [egress, proxy, signals, outbound, https, grant, policy, operator, webhook]
+complexity: advanced
+capabilities: [enabled, methods, parameters, proxy, respond, signals]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+routes: 2
+grants:
+  - kind: proxy
+    description: The upstream origin, granted in an operator policy generated with urlcode permissions.
+  - kind: signals
+    description: The hook origin, granted the same way; signals are best effort and never retried.
+files: [urlcode.yaml, README.md]
+tests:
+  commands:
+    - node src/cli.ts permissions --project examples/egress
+    - node src/cli.ts validate --local --project examples/egress --policy /operator/egress-policy.json
+behavior:
+  - without the policy the project refuses to activate; nothing here reaches the network during authoring inspection