@mccaskie-labs/workbench-config 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.6
+
+### Patch Changes
+
+- Add the email-inbound capability manifest (step 4.10): the inbound email tools, their refusals, rules and probes.
+
 ## 0.1.5
 
 ### Patch Changes

package/capabilities/email-inbound.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "email-inbound",
+  "title": "Inbound email to the project's own Worker",
+  "summary": "Email Routing receives mail on a domain in the project's namespace and runs one routing rule per address, each sending the mail to one of the project's own Workers. The Worker's email() handler parses it with postal-mime and the app stores or rejects it. Mail is never forwarded outside the project.",
+  "status": "built",
+  "surfaces": {
+    "tools": [
+      "cf_email_routing_enable",
+      "cf_email_routing_list",
+      "cf_email_routing_rule_create",
+      "cf_email_routing_rule_delete"
+    ]
+  },
+  "limits": [
+    {
+      "id": "email-inbound.address-length",
+      "value": 90,
+      "unit": "characters",
+      "per": "address",
+      "enforced_by": "control",
+      "refusal": "invalid_address"
+    }
+  ],
+  "actions": [
+    {
+      "tool": "cf_email_routing_enable",
+      "gate": "free",
+      "ships": "4"
+    },
+    {
+      "tool": "cf_email_routing_list",
+      "gate": "free",
+      "ships": "4"
+    },
+    {
+      "tool": "cf_email_routing_rule_create",
+      "gate": "free",
+      "ships": "4"
+    },
+    {
+      "tool": "cf_email_routing_rule_delete",
+      "gate": "two_step",
+      "ships": "4"
+    }
+  ],
+  "errors": [
+    {
+      "code": "out_of_scope",
+      "http": 403,
+      "retryable": false,
+      "meaning": "A domain outside the project's namespace, another project's Worker or another project's rule"
+    },
+    {
+      "code": "catch_all",
+      "http": 400,
+      "retryable": false,
+      "meaning": "A catch-all address; Control routes only one literal address per rule"
+    },
+    {
+      "code": "routing_not_enabled",
+      "http": 409,
+      "retryable": false,
+      "meaning": "Email Routing isn't on for the address's domain yet (cf_email_routing_enable)"
+    },
+    {
+      "code": "name_taken",
+      "http": 409,
+      "retryable": false,
+      "meaning": "A mail record or rule exists that Control didn't create for the project; Control never adopts"
+    }
+  ],
+  "rules": [
+    {
+      "id": "email-inbound.own-worker",
+      "kind": "must",
+      "text": "Route an address only to one of the project's own Workers. A rule naming another project's Worker is refused with out_of_scope.",
+      "enforced_by": "control",
+      "probe": "email-inbound.other-worker"
+    },
+    {
+      "id": "email-inbound.no-forward",
+      "kind": "must_not",
+      "text": "Forward inbound mail outside the project. The template's receiveEmail gives the app the parsed mail and a reject function, not the message.",
+      "enforced_by": "review",
+      "probe": "email-inbound.roundtrip"
+    },
+    {
+      "id": "email-inbound.reject-on-failure",
+      "kind": "must",
+      "text": "Reject a message the app can't store (throw from handleEmail, or call reject) rather than drop it silently.",
+      "enforced_by": "review",
+      "probe": "email-inbound.roundtrip"
+    }
+  ],
+  "examples": [
+    {
+      "id": "email-inbound.example.handler",
+      "title": "Store inbound mail",
+      "lang": "ts",
+      "probe": "email-inbound.roundtrip",
+      "code": "export async function handleEmail(mail, env, ctx, { reject }) {\n  if (!mail.to.some((t) => t.address === 'inbox@wb-probe-staging.mccaskielabs.app')) return reject('Unknown mailbox')\n  await saveMail(env, { message_id: mail.message_id, subject: mail.subject, text: mail.text, received_at: mail.received_at })\n}"
+    }
+  ],
+  "probes": [
+    {
+      "id": "email-inbound.roundtrip",
+      "half": "runtime",
+      "expect": "pass",
+      "note": "Sends a mail through the Gateway to inbox@ on the receiving domain; the Email Worker stores it and the console shows send-to-stored time. Needs step 4.9 (outbound) and a store (step 4.11)"
+    },
+    {
+      "id": "email-inbound.other-worker",
+      "half": "drill",
+      "expect": "refused_as_expected",
+      "refusal": "out_of_scope",
+      "note": "cf_email_routing_rule_create naming another project's Worker"
+    },
+    {
+      "id": "email-inbound.rule-delete",
+      "half": "drill",
+      "expect": "pass",
+      "two_step": true,
+      "note": "cf_email_routing_rule_delete returns a confirmation and changes nothing until Robert approves"
+    }
+  ]
+}

package/capabilities/email-inbound.md

@@ -0,0 +1,19 @@
+# Inbound email
+
+A project receives mail on a domain in its namespace, for example `wb-probe-staging.mccaskielabs.app`, and each address it uses is routed to one of its own Workers. Project-owned zones such as `wbprobe.com` join the namespace with `cf_zone_attach` (phase 6).
+
+## Setting it up (Claude, through Control)
+
+1. `cf_email_routing_enable domain=<domain>`. Cloudflare adds its MX and SPF records on that name only; the apex's locked-down baseline stays as it is. Control records the records for the project, so `cf_dns_delete` removes them again.
+2. `cf_email_routing_rule_create address=inbox@<domain> worker=<id>-staging`. One literal address, one Worker. No catch-alls, no forwarding.
+3. `cf_email_routing_list` shows the domains and rules. `cf_email_routing_rule_delete` (two-step) stops an address.
+
+## In the Worker
+
+The template's `src/email.js` exports `receiveEmail`, and `src/index.js` wires it to `handleEmail(mail, env, ctx, { reject })`. `mail` has `received_at`, `envelope_from`, `envelope_to`, `raw_size`, `message_id`, `from`, `to`, `subject`, `date`, `text`, `html`, `headers` and `attachments` (each with `filename`, `mime_type`, `content_id`, `size` and `content`). Store what the app needs and return, or call `reject(reason)` to bounce the message. A handler that throws rejects it too.
+
+The starter `handleEmail` rejects everything, so routing an address before the app handles mail bounces it rather than losing it.
+
+## Limits
+
+Email Routing takes messages up to 25 MiB. Addresses are at most 90 characters, and the part before `@` takes letters, digits, dot, underscore, plus and hyphen.

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "068bbebdf4de";
+export declare const MANIFEST_VERSION: "928d1b370728";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -416,6 +416,107 @@ export declare const capabilities: {
             readonly note: "sb_query on production with a write returns a confirmation, not a result";
         }];
     };
+    readonly "email-inbound": {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "email-inbound";
+        readonly title: "Inbound email to the project's own Worker";
+        readonly summary: "Email Routing receives mail on a domain in the project's namespace and runs one routing rule per address, each sending the mail to one of the project's own Workers. The Worker's email() handler parses it with postal-mime and the app stores or rejects it. Mail is never forwarded outside the project.";
+        readonly status: "built";
+        readonly surfaces: {
+            readonly tools: readonly ["cf_email_routing_enable", "cf_email_routing_list", "cf_email_routing_rule_create", "cf_email_routing_rule_delete"];
+        };
+        readonly limits: readonly [{
+            readonly id: "email-inbound.address-length";
+            readonly value: 90;
+            readonly unit: "characters";
+            readonly per: "address";
+            readonly enforced_by: "control";
+            readonly refusal: "invalid_address";
+        }];
+        readonly actions: readonly [{
+            readonly tool: "cf_email_routing_enable";
+            readonly gate: "free";
+            readonly ships: "4";
+        }, {
+            readonly tool: "cf_email_routing_list";
+            readonly gate: "free";
+            readonly ships: "4";
+        }, {
+            readonly tool: "cf_email_routing_rule_create";
+            readonly gate: "free";
+            readonly ships: "4";
+        }, {
+            readonly tool: "cf_email_routing_rule_delete";
+            readonly gate: "two_step";
+            readonly ships: "4";
+        }];
+        readonly errors: readonly [{
+            readonly code: "out_of_scope";
+            readonly http: 403;
+            readonly retryable: false;
+            readonly meaning: "A domain outside the project's namespace, another project's Worker or another project's rule";
+        }, {
+            readonly code: "catch_all";
+            readonly http: 400;
+            readonly retryable: false;
+            readonly meaning: "A catch-all address; Control routes only one literal address per rule";
+        }, {
+            readonly code: "routing_not_enabled";
+            readonly http: 409;
+            readonly retryable: false;
+            readonly meaning: "Email Routing isn't on for the address's domain yet (cf_email_routing_enable)";
+        }, {
+            readonly code: "name_taken";
+            readonly http: 409;
+            readonly retryable: false;
+            readonly meaning: "A mail record or rule exists that Control didn't create for the project; Control never adopts";
+        }];
+        readonly rules: readonly [{
+            readonly id: "email-inbound.own-worker";
+            readonly kind: "must";
+            readonly text: "Route an address only to one of the project's own Workers. A rule naming another project's Worker is refused with out_of_scope.";
+            readonly enforced_by: "control";
+            readonly probe: "email-inbound.other-worker";
+        }, {
+            readonly id: "email-inbound.no-forward";
+            readonly kind: "must_not";
+            readonly text: "Forward inbound mail outside the project. The template's receiveEmail gives the app the parsed mail and a reject function, not the message.";
+            readonly enforced_by: "review";
+            readonly probe: "email-inbound.roundtrip";
+        }, {
+            readonly id: "email-inbound.reject-on-failure";
+            readonly kind: "must";
+            readonly text: "Reject a message the app can't store (throw from handleEmail, or call reject) rather than drop it silently.";
+            readonly enforced_by: "review";
+            readonly probe: "email-inbound.roundtrip";
+        }];
+        readonly examples: readonly [{
+            readonly id: "email-inbound.example.handler";
+            readonly title: "Store inbound mail";
+            readonly lang: "ts";
+            readonly code: "export async function handleEmail(mail, env, ctx, { reject }) {\n  if (!mail.to.some((t) => t.address === 'inbox@wb-probe-staging.mccaskielabs.app')) return reject('Unknown mailbox')\n  await saveMail(env, { message_id: mail.message_id, subject: mail.subject, text: mail.text, received_at: mail.received_at })\n}";
+            readonly probe: "email-inbound.roundtrip";
+        }];
+        readonly probes: readonly [{
+            readonly id: "email-inbound.roundtrip";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly note: "Sends a mail through the Gateway to inbox@ on the receiving domain; the Email Worker stores it and the console shows send-to-stored time. Needs step 4.9 (outbound) and a store (step 4.11)";
+        }, {
+            readonly id: "email-inbound.other-worker";
+            readonly half: "drill";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "out_of_scope";
+            readonly note: "cf_email_routing_rule_create naming another project's Worker";
+        }, {
+            readonly id: "email-inbound.rule-delete";
+            readonly half: "drill";
+            readonly expect: "pass";
+            readonly two_step: true;
+            readonly note: "cf_email_routing_rule_delete returns a confirmation and changes nothing until Robert approves";
+        }];
+    };
     readonly gateway: {
         readonly $schema: "./schema.json";
         readonly format: 1;

package/dist/capabilities.gen.js

@@ -1,6 +1,6 @@
 // Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
 // check:capabilities fails in Checks when this file is stale.
-export const MANIFEST_VERSION = "068bbebdf4de";
+export const MANIFEST_VERSION = "928d1b370728";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -577,6 +577,134 @@ export const capabilities = {
             }
         ]
     },
+    "email-inbound": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "email-inbound",
+        "title": "Inbound email to the project's own Worker",
+        "summary": "Email Routing receives mail on a domain in the project's namespace and runs one routing rule per address, each sending the mail to one of the project's own Workers. The Worker's email() handler parses it with postal-mime and the app stores or rejects it. Mail is never forwarded outside the project.",
+        "status": "built",
+        "surfaces": {
+            "tools": [
+                "cf_email_routing_enable",
+                "cf_email_routing_list",
+                "cf_email_routing_rule_create",
+                "cf_email_routing_rule_delete"
+            ]
+        },
+        "limits": [
+            {
+                "id": "email-inbound.address-length",
+                "value": 90,
+                "unit": "characters",
+                "per": "address",
+                "enforced_by": "control",
+                "refusal": "invalid_address"
+            }
+        ],
+        "actions": [
+            {
+                "tool": "cf_email_routing_enable",
+                "gate": "free",
+                "ships": "4"
+            },
+            {
+                "tool": "cf_email_routing_list",
+                "gate": "free",
+                "ships": "4"
+            },
+            {
+                "tool": "cf_email_routing_rule_create",
+                "gate": "free",
+                "ships": "4"
+            },
+            {
+                "tool": "cf_email_routing_rule_delete",
+                "gate": "two_step",
+                "ships": "4"
+            }
+        ],
+        "errors": [
+            {
+                "code": "out_of_scope",
+                "http": 403,
+                "retryable": false,
+                "meaning": "A domain outside the project's namespace, another project's Worker or another project's rule"
+            },
+            {
+                "code": "catch_all",
+                "http": 400,
+                "retryable": false,
+                "meaning": "A catch-all address; Control routes only one literal address per rule"
+            },
+            {
+                "code": "routing_not_enabled",
+                "http": 409,
+                "retryable": false,
+                "meaning": "Email Routing isn't on for the address's domain yet (cf_email_routing_enable)"
+            },
+            {
+                "code": "name_taken",
+                "http": 409,
+                "retryable": false,
+                "meaning": "A mail record or rule exists that Control didn't create for the project; Control never adopts"
+            }
+        ],
+        "rules": [
+            {
+                "id": "email-inbound.own-worker",
+                "kind": "must",
+                "text": "Route an address only to one of the project's own Workers. A rule naming another project's Worker is refused with out_of_scope.",
+                "enforced_by": "control",
+                "probe": "email-inbound.other-worker"
+            },
+            {
+                "id": "email-inbound.no-forward",
+                "kind": "must_not",
+                "text": "Forward inbound mail outside the project. The template's receiveEmail gives the app the parsed mail and a reject function, not the message.",
+                "enforced_by": "review",
+                "probe": "email-inbound.roundtrip"
+            },
+            {
+                "id": "email-inbound.reject-on-failure",
+                "kind": "must",
+                "text": "Reject a message the app can't store (throw from handleEmail, or call reject) rather than drop it silently.",
+                "enforced_by": "review",
+                "probe": "email-inbound.roundtrip"
+            }
+        ],
+        "examples": [
+            {
+                "id": "email-inbound.example.handler",
+                "title": "Store inbound mail",
+                "lang": "ts",
+                "code": "export async function handleEmail(mail, env, ctx, { reject }) {\n  if (!mail.to.some((t) => t.address === 'inbox@wb-probe-staging.mccaskielabs.app')) return reject('Unknown mailbox')\n  await saveMail(env, { message_id: mail.message_id, subject: mail.subject, text: mail.text, received_at: mail.received_at })\n}",
+                "probe": "email-inbound.roundtrip"
+            }
+        ],
+        "probes": [
+            {
+                "id": "email-inbound.roundtrip",
+                "half": "runtime",
+                "expect": "pass",
+                "note": "Sends a mail through the Gateway to inbox@ on the receiving domain; the Email Worker stores it and the console shows send-to-stored time. Needs step 4.9 (outbound) and a store (step 4.11)"
+            },
+            {
+                "id": "email-inbound.other-worker",
+                "half": "drill",
+                "expect": "refused_as_expected",
+                "refusal": "out_of_scope",
+                "note": "cf_email_routing_rule_create naming another project's Worker"
+            },
+            {
+                "id": "email-inbound.rule-delete",
+                "half": "drill",
+                "expect": "pass",
+                "two_step": true,
+                "note": "cf_email_routing_rule_delete returns a confirmation and changes nothing until Robert approves"
+            }
+        ]
+    },
     "gateway": {
         "$schema": "./schema.json",
         "format": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",