@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/recipes/protected-download/recipe.yaml

@@ -0,0 +1,31 @@
+id: protected-download
+description: Native attachment download that only the operator-installed auth extension lets through.
+tags: [download, attachment, protected, auth, authenticated, file, private, extension, content-disposition, "401"]
+complexity: advanced
+capabilities: [download, enabled, extension, methods, policies.extensions]
+targets: {self-hosted: conditional, aws: conditional, vercel: conditional, cloudflare: refused, static: refused}
+routes: 1
+services:
+  - name: auth extension
+    description: An operator registry providing the `auth` extension; the authenticated-json-api README shows a minimal protocol fixture.
+grants:
+  - kind: extension
+    description: The registration pins projectSha256 to this exact revision, including the attachment.
+  - kind: origin
+    description: The canonical origin passed as --origin at every command that activates the project.
+inputs:
+  - name: attachment
+    file: files/report.txt
+    description: Replace the placeholder and adjust filename and contentType in urlcode.yaml.
+files: [urlcode.yaml, files/report.txt, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - 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
+behavior:
+  - GET /downloads/report without credentials answers 401
+  - GET with the accepted credential answers 200, Content-Disposition attachment and Cache-Control no-store
+  - HEAD mirrors both cases with an empty body
+  - no guest code runs; the file is served natively and snapshotted at activation

package/recipes/protected-download/tests/requests.json

@@ -0,0 +1,32 @@
+[
+  {
+    "path": "/downloads/report",
+    "status": 401
+  },
+  {
+    "path": "/downloads/report",
+    "headers": {
+      "authorization": "Bearer demo-token"
+    },
+    "status": 200,
+    "expectBody": "Quarterly report (placeholder). Replace this file with the real attachment.\n",
+    "expectHeaders": {
+      "content-disposition": "attachment; filename=quarterly-report.txt",
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/downloads/report",
+    "method": "HEAD",
+    "headers": {
+      "authorization": "Bearer demo-token"
+    },
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/downloads/report",
+    "method": "HEAD",
+    "status": 401
+  }
+]

package/recipes/protected-download/urlcode.yaml

@@ -0,0 +1,15 @@
+version: "1"
+extensions:
+  auth:
+    version: "1"
+    config:
+      realm: downloads
+routes:
+  /downloads/report:
+    description: Attachment served natively, only after the auth extension authorizes the caller.
+    download:
+      file: files/report.txt
+      filename: quarterly-report.txt
+      contentType: text/plain
+      cacheControl: no-store
+    auth: true

package/recipes/redirect/README.md

@@ -0,0 +1,7 @@
+# Permanent documentation redirect
+
+Run `urlcode validate --local --project .` and `urlcode serve --project .`.
+`/docs?campaign=launch&private=discarded` redirects to
+`https://example.com/documentation?campaign=launch` with status 301.
+Replace the example destination before deploying. Incoming query parameters are
+not forwarded unless explicitly allowlisted.

package/recipes/redirect/recipe.yaml

@@ -0,0 +1,25 @@
+id: redirect
+description: Permanent redirect that forwards only an allowlisted query key.
+tags: [redirect, permanent, "301", query, passthrough, documentation, native]
+complexity: starter
+capabilities: [enabled, methods, redirect]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: compatible}
+routes: 1
+inputs:
+  - name: destination
+    file: urlcode.yaml
+    description: Replace https://example.com/documentation with the real target.
+  - name: query.pass
+    file: urlcode.yaml
+    description: The query keys forwarded to the destination; everything else is dropped.
+files: [urlcode.yaml, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project .
+    - urlcode test --project .
+    - urlcode audit --project . --expect-routes 1
+behavior:
+  - GET /docs?campaign=launch&private=x answers 301 to https://example.com/documentation?campaign=launch
+  - HEAD answers the same status with an empty body
+  - unknown paths answer 404

package/recipes/redirect/tests/requests.json

@@ -0,0 +1,19 @@
+[
+  {
+    "path": "/docs?campaign=launch&private=discarded",
+    "status": 301,
+    "expectHeaders": {
+      "location": "https://example.com/documentation?campaign=launch"
+    }
+  },
+  {
+    "path": "/docs",
+    "method": "HEAD",
+    "status": 301,
+    "expectBody": ""
+  },
+  {
+    "path": "/missing",
+    "status": 404
+  }
+]

package/recipes/redirect/urlcode.yaml

@@ -0,0 +1,9 @@
+version: "1"
+routes:
+  /docs:
+    description: Move documentation and preserve only the declared campaign key.
+    redirect:
+      url: https://example.com/documentation
+      status: 301
+      query:
+        pass: [campaign]

package/recipes/static-plus-api/README.md

@@ -0,0 +1,15 @@
+# Static site with a JSON API
+
+Run `urlcode validate --local --project .`, `urlcode test --project .` and
+`urlcode audit --project . --expect-routes 3`.
+
+`/` serves `public/index.html`, `/assets/*` serves everything under
+`public/assets` (with `index.html` for the directory itself), and `/api/info`
+is a sandboxed function returning JSON built from literal `args`. Pages and
+assets are native: no guest code runs for them, and they are snapshotted at
+activation, so new files need a reload. Edit the HTML, add files under
+`public/assets`, and change or extend `functions/info.mjs`.
+
+The function needs the self-hosted runtime; drop `/api/info` to deploy the
+static part on a serverless target. Static mounts cannot escape their
+directory, and the recipe sets explicit caching so nothing is guessed.

package/recipes/static-plus-api/functions/info.mjs

@@ -0,0 +1,3 @@
+export default function info(request, {args}) {
+  return Response.json({name: args.name, version: args.version});
+}

package/recipes/static-plus-api/public/assets/index.html

@@ -0,0 +1,3 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>Assets</title></head>
+<body><p>Asset directory index.</p></body></html>

package/recipes/static-plus-api/public/assets/site.css

@@ -0,0 +1 @@
+body { font-family: system-ui, sans-serif; margin: 2rem; }

package/recipes/static-plus-api/public/index.html

@@ -0,0 +1,8 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Example site</title><link rel="stylesheet" href="/assets/site.css"></head>
+<body>
+<h1>Example site</h1>
+<p>Static pages are served natively; <a href="/api/info">/api/info</a> is a sandboxed function.</p>
+</body>
+</html>

package/recipes/static-plus-api/recipe.yaml

@@ -0,0 +1,29 @@
+id: static-plus-api
+description: A native static site (home page and an assets directory) next to one sandboxed JSON endpoint.
+tags: [static, site, page, html, assets, css, api, json, function, cache-control, website]
+complexity: intermediate
+capabilities: [enabled, function, methods, page, response.headers, static]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
+routes: 3
+inputs:
+  - name: pages
+    file: public/index.html
+    description: The home page and everything under public/assets.
+  - name: args
+    file: urlcode.yaml
+    description: The literal name and version /api/info reports.
+  - name: handler
+    file: functions/info.mjs
+    description: Replace the literal JSON with the real endpoint.
+files: [urlcode.yaml, public/index.html, public/assets/index.html, public/assets/site.css, functions/info.mjs, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project .
+    - urlcode test --project .
+    - urlcode audit --project . --expect-routes 3
+behavior:
+  - GET / answers the home page as text/html with Cache-Control no-cache
+  - GET /assets/site.css answers text/css cached for one hour; /assets/ answers the directory index; missing files answer 404
+  - GET /api/info answers 200 {"name":"Example site","version":"1"} with no-store
+  - drop /api/info to deploy the static part on a serverless target

package/recipes/static-plus-api/tests/requests.json

@@ -0,0 +1,56 @@
+[
+  {
+    "path": "/",
+    "status": 200,
+    "expectHeaders": {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-cache"
+    }
+  },
+  {
+    "path": "/",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/assets/site.css",
+    "status": 200,
+    "expectBody": "body { font-family: system-ui, sans-serif; margin: 2rem; }\n",
+    "expectHeaders": {
+      "content-type": "text/css; charset=utf-8",
+      "cache-control": "public, max-age=3600"
+    }
+  },
+  {
+    "path": "/assets/",
+    "status": 200,
+    "expectHeaders": {
+      "content-type": "text/html; charset=utf-8"
+    }
+  },
+  {
+    "path": "/assets/site.css",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/assets/missing.css",
+    "status": 404
+  },
+  {
+    "path": "/api/info",
+    "status": 200,
+    "expectBody": "{\"name\":\"Example site\",\"version\":\"1\"}",
+    "expectHeaders": {
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/api/info",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  }
+]

package/recipes/static-plus-api/urlcode.yaml

@@ -0,0 +1,23 @@
+version: "1"
+routes:
+  /:
+    description: The site's home page served natively from public/index.html.
+    page:
+      file: public/index.html
+      cacheControl: no-cache
+  /assets/*:
+    description: Every file under public/assets, with a directory index and one-hour caching.
+    static:
+      directory: public/assets
+      index: index.html
+      cacheControl: public, max-age=3600
+  /api/info:
+    description: A small JSON endpoint next to the static site, computed in the sandbox.
+    function:
+      source: functions/info.mjs
+      args:
+        name: Example site
+        version: "1"
+    response:
+      headers:
+        Cache-Control: no-store

package/recipes/typescript/README.md

@@ -0,0 +1,8 @@
+# Build-time TypeScript guest
+
+Run `urlcode build-typescript --project . --out ../hello-built` with a new output
+directory, then `urlcode validate --local --project ../hello-built` and
+`urlcode serve --project ../hello-built`. GET `/hello` returns JSON.
+TypeScript is transpiled ahead of time. The runtime executes only the emitted
+JavaScript, in QuickJS/WASM for a `sandbox: true` route and in-process for a
+trusted one. The build does not type-check or read tsconfig.json.

package/recipes/typescript/functions/hello.ts

@@ -0,0 +1,5 @@
+interface Greeting { message: string }
+export default function hello(): Response {
+  const greeting: Greeting = {message: 'Hello from a compiled TypeScript guest'};
+  return Response.json(greeting);
+}

package/recipes/typescript/recipe.yaml

@@ -0,0 +1,23 @@
+id: typescript
+description: Typed guest function transpiled ahead of time; only the emitted JavaScript runs in the sandbox.
+tags: [typescript, function, build, typed, compile, sandbox]
+complexity: intermediate
+capabilities: [enabled, function, methods]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
+routes: 1
+inputs:
+  - name: handler
+    file: functions/hello.ts
+    description: The typed guest; keep to the Request/Response sandbox API.
+files: [urlcode.yaml, functions/hello.ts, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode build-typescript --project . --out ../hello-built
+    - urlcode validate --local --project ../hello-built
+    - urlcode test --project ../hello-built
+    - urlcode audit --project ../hello-built --expect-routes 1
+behavior:
+  - after the build, GET /hello answers 200 JSON from the compiled guest
+  - the unbuilt project does not activate; .ts sources never run
+  - POST answers 405

package/recipes/typescript/tests/requests.json

@@ -0,0 +1,18 @@
+[
+  {
+    "path": "/hello",
+    "status": 200,
+    "expectBody": "{\"message\":\"Hello from a compiled TypeScript guest\"}"
+  },
+  {
+    "path": "/hello",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/hello",
+    "method": "POST",
+    "status": 405
+  }
+]

package/recipes/typescript/urlcode.yaml

@@ -0,0 +1,5 @@
+version: "1"
+routes:
+  /hello:
+    function:
+      source: functions/hello.ts

package/recipes/webhook-receiver/README.md

@@ -0,0 +1,20 @@
+# Webhook receiver
+
+Run `urlcode validate --local --project .`, `urlcode test --project .` and
+`urlcode audit --project . --expect-routes 1`.
+
+`POST /webhook` accepts at most 64 KiB of `application/json`. The runtime
+rejects other methods (405), other content types (415), oversized bodies (413)
+and malformed JSON (400) before the sandbox runs. The route declares
+`sandbox: true`: functions/middleware run trusted by default, but a
+third-party sender's payload is exactly the input a project doesn't fully
+trust, so this recipe isolates parsing it (docs/FUNCTION-SECURITY.md). The
+function then requires an
+`X-Webhook-Event` header and a JSON object carrying a string `id`, and answers
+`202 {"received":true,...}`.
+
+This recipe verifies shape, not origin. Nothing here checks a signature: the
+guest has no crypto API and no network access, so signed webhooks belong behind
+an operator-installed extension or a trusted host in front of this route. Edit
+`functions/receive.mjs` to check the fields your sender guarantees, and keep
+the body limit as small as the sender allows.

package/recipes/webhook-receiver/functions/receive.mjs

@@ -0,0 +1,16 @@
+// The runtime has already enforced method, content type, size and JSON syntax.
+// The guest checks the shape it cares about and acknowledges; it has no network
+// access, so forwarding happens through a declared route signal or a host process
+// that reads the runtime log, never from here.
+const eventPattern = /^[a-z][a-z0-9_.-]{0,63}$/;
+export default async function receive(request) {
+  const event = request.headers.get('x-webhook-event');
+  if (!event || !eventPattern.test(event)) {
+    return Response.json({error: 'missing or invalid X-Webhook-Event header'}, {status: 400});
+  }
+  const payload = await request.json();
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload) || typeof payload.id !== 'string') {
+    return Response.json({error: 'body must be a JSON object with a string id'}, {status: 422});
+  }
+  return Response.json({received: true, event, id: payload.id}, {status: 202});
+}

package/recipes/webhook-receiver/recipe.yaml

@@ -0,0 +1,27 @@
+id: webhook-receiver
+description: Accept a bounded JSON event that names its type in a header, check its shape and acknowledge with 202.
+tags: [webhook, receiver, event, post, json, body, "202", callback, ingest, function]
+complexity: starter
+capabilities: [enabled, function, methods, request.body, response.headers]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
+routes: 1
+inputs:
+  - name: shape check
+    file: functions/receive.mjs
+    description: The header name, event pattern and payload fields the sender guarantees.
+  - name: maxBytes
+    file: urlcode.yaml
+    description: The body limit (64 KiB); keep it as small as the sender allows.
+files: [urlcode.yaml, functions/receive.mjs, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project .
+    - urlcode test --project .
+    - urlcode audit --project . --expect-routes 1
+behavior:
+  - POST /webhook with application/json, X-Webhook-Event and a string id answers 202 {"received":true,"event":...,"id":...}
+  - a missing event header answers 400; a body that is not an object with a string id answers 422
+  - other methods 405, other content types 415, oversized bodies 413 and malformed JSON 400 before the sandbox runs
+  - the guest has no crypto or network API, so signatures are not verified here; put signed webhooks behind an operator extension or trusted host
+  - "the route declares sandbox: true, isolating the third-party payload from the trusted-by-default execution every other function/middleware route gets"

package/recipes/webhook-receiver/tests/requests.json

@@ -0,0 +1,59 @@
+[
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json",
+      "x-webhook-event": "order.created"
+    },
+    "body": "{\"id\":\"evt_123\",\"total\":42}",
+    "status": 202,
+    "expectBody": "{\"received\":true,\"event\":\"order.created\",\"id\":\"evt_123\"}",
+    "expectHeaders": {
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{\"id\":\"evt_123\"}",
+    "status": 400
+  },
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json",
+      "x-webhook-event": "order.created"
+    },
+    "body": "[1,2,3]",
+    "status": 422
+  },
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json",
+      "x-webhook-event": "order.created"
+    },
+    "body": "{not json",
+    "status": 400
+  },
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "text/plain",
+      "x-webhook-event": "order.created"
+    },
+    "body": "id=1",
+    "status": 415
+  },
+  {
+    "path": "/webhook",
+    "status": 405
+  }
+]

package/recipes/webhook-receiver/urlcode.yaml

@@ -0,0 +1,23 @@
+version: "1"
+routes:
+  /webhook:
+    description: Accept a bounded JSON event body that names its event type in a header.
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 65536
+        contentTypes: [application/json]
+        format: json
+    function:
+      source: functions/receive.mjs
+    # A third-party sender's payload is exactly the kind of input this
+    # project does not fully trust (docs/AI-AUTHORING.md, "Deciding when a
+    # route needs sandbox: true"), even after body/content-type validation:
+    # isolate parsing it from the rest of the process.
+    sandbox: true
+    sandboxReason: >-
+      Third-party webhook payload; isolate parsing it even after body/content-type validation.
+    response:
+      headers:
+        Cache-Control: no-store

package/schemas/recipe.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/jimhoyd-com/urlcode/main/schemas/recipe.schema.json",
+  "title": "URLCode recipe and example metadata",
+  "description": "The recipe.yaml and example.yaml shape searched by `urlcode recipes search` and `urlcode examples search`. capabilities, targets and routes are derived from the capability preflight and checked by `npm run check`; the rest is written by hand.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "description", "tags", "complexity", "files"],
+  "properties": {
+    "id": {
+      "description": "The directory name under recipes/ or examples/.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 64
+    },
+    "description": {
+      "description": "One sentence; searched.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300
+    },
+    "tags": {
+      "description": "Lower-case search words; searched.",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[a-z0-9][a-z0-9.-]{0,39}$"}
+    },
+    "complexity": {
+      "enum": ["starter", "intermediate", "advanced"]
+    },
+    "runnable": {
+      "description": "false for a directory with no urlcode.yaml (operator rules, monitoring configuration, scripts). Such entries carry no capabilities, targets or routes.",
+      "type": "boolean",
+      "default": true
+    },
+    "capabilities": {
+      "description": "Derived: every capability name the preflight reports for the project, sorted; searched.",
+      "type": "array",
+      "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[a-z][a-zA-Z.]{0,39}$"}
+    },
+    "targets": {
+      "description": "Derived: the capability preflight verdict per target. compatible means no issue; otherwise the strongest issue (refused, unknown, conditional).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["self-hosted", "aws", "vercel", "cloudflare", "static"],
+      "properties": {
+        "self-hosted": {"$ref": "#/$defs/verdict"},
+        "aws": {"$ref": "#/$defs/verdict"},
+        "vercel": {"$ref": "#/$defs/verdict"},
+        "cloudflare": {"$ref": "#/$defs/verdict"},
+        "static": {"$ref": "#/$defs/verdict"}
+      }
+    },
+    "routes": {
+      "description": "Derived: the number of routes after site expansion; the value for --expect-routes.",
+      "type": "integer",
+      "minimum": 0
+    },
+    "services": {
+      "description": "External services the project needs at activation: an operator-installed extension package, a hook endpoint, a store.",
+      "type": "array",
+      "maxItems": 16,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "description"],
+        "properties": {
+          "name": {"type": "string", "minLength": 1, "maxLength": 80},
+          "description": {"type": "string", "minLength": 1, "maxLength": 300}
+        }
+      }
+    },
+    "grants": {
+      "description": "Operator grants the project needs before it activates; none of them come from project files.",
+      "type": "array",
+      "maxItems": 16,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "description"],
+        "properties": {
+          "kind": {"enum": ["extension", "signals", "proxy", "env", "secret", "origin"]},
+          "description": {"type": "string", "minLength": 1, "maxLength": 300}
+        }
+      }
+    },
+    "inputs": {
+      "description": "What to edit before use.",
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "file", "description"],
+        "properties": {
+          "name": {"type": "string", "minLength": 1, "maxLength": 80},
+          "file": {"type": "string", "minLength": 1, "maxLength": 200},
+          "description": {"type": "string", "minLength": 1, "maxLength": 300}
+        }
+      }
+    },
+    "files": {
+      "description": "Every file the recipe copies (recipes) or the files worth reading first (examples), project-relative.",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 256,
+      "uniqueItems": true,
+      "items": {"type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9_][A-Za-z0-9_./-]*$"}
+    },
+    "tests": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["commands"],
+      "properties": {
+        "fixtures": {"description": "The request fixture file, when the project has one.", "type": "string", "maxLength": 200},
+        "commands": {
+          "description": "The exact commands that validate, test and audit the project, run from its directory.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 12,
+          "items": {"type": "string", "minLength": 1, "maxLength": 300}
+        }
+      }
+    },
+    "behavior": {
+      "description": "Expected behavior, one observable statement per line.",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "items": {"type": "string", "minLength": 1, "maxLength": 300}
+    }
+  },
+  "$defs": {
+    "verdict": {"enum": ["compatible", "conditional", "refused", "unknown"]}
+  }
+}