@premium-cms/plugin-cloudflare-email-byo 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# cloudflare-email-byo
+
+**Email from the site owner's own Cloudflare account.**
+
+EmDash's built-in `cloudflareEmail` provider sends through the Worker's
+`send_email` binding — which belongs to whichever Cloudflare account deployed
+the Worker. On a fleet that means every project's mail leaves from the
+platform's account, on the platform's sending domain and reputation, against
+the platform's quota.
+
+This provider calls the Cloudflare Email Sending **REST API** with an API token
+the owner enters in the admin, so mail leaves from _their_ account and _their_
+verified domain. The platform never holds the credential.
+
+## Setup (for the site owner)
+
+1. In your own Cloudflare dashboard, onboard a domain for **Email Sending**.
+2. Create an **API token** with email sending permission.
+3. Open the plugin's **Email (own Cloudflare)** settings page and fill in the
+   account ID, token, and sender address.
+4. Click **Send test email**.
+5. Under **Settings → Email**, select `cloudflare-email-byo` as the provider.
+
+Step 5 matters: EmDash auto-selects a provider only when exactly one is active.
+With both this and the built-in provider installed, the choice must be explicit.
+
+## Settings
+
+| Field       | Notes                                                                    |
+| ----------- | ------------------------------------------------------------------------ |
+| Account ID  | 32 hex characters; validated before any request is made                  |
+| API token   | Stored in plugin KV, never returned by any route or rendered into a page |
+| Send from   | Must be on a domain onboarded for Email Sending in _your_ account        |
+| Sender name | Optional                                                                 |
+| Reply-To    | Optional                                                                 |
+
+Leaving the token field blank on save **keeps** the stored token — Block Kit
+submits an empty string for an untouched secret field, so writing it blindly
+would wipe a working credential on every unrelated edit. Type `clear` to remove it.
+
+## Trust contract
+
+```jsonc
+"capabilities": ["hooks.email-transport:register", "network:request"],
+"allowedHosts": ["api.cloudflare.com"]
+```
+
+`hooks.email-transport:register` is what permits the exclusive `email:deliver`
+hook — **without it the hook is silently skipped at registration** and the
+plugin appears to do nothing at all.
+
+`network:request` is the host-restricted form (not `:unrestricted`), pinned to
+`api.cloudflare.com` via `allowedHosts`. The owner's API token is the most
+sensitive thing here; restricting egress to the single host that token is valid
+for means a bug or a bad setting cannot post it anywhere else.
+
+## The REST API is not the Workers binding
+
+Field names differ, and getting them wrong produces a 400 that reads like a
+domain-verification problem:
+
+| Workers binding         | REST API                                             |
+| ----------------------- | ---------------------------------------------------- |
+| `from: { email, name }` | `from: { address, name }`                            |
+| `replyTo`               | `reply_to`                                           |
+| returns `messageId`     | returns `delivered` / `permanent_bounces` / `queued` |
+
+A permanent bounce comes back on **HTTP 200** with the recipient listed in
+`permanent_bounces`, so a naive status check reports success on a message that
+was never delivered. This plugin treats that as a failure.
+
+## Working on it
+
+```bash
+bun install              # from the repo root
+npx vitest run           # 19 tests, no CMS and no network
+npx tsc --noEmit
+npx emdash-plugin build
+```
+
+The tests assert the REST contract itself — endpoint, auth header, `address`
+vs `email`, `reply_to` casing — plus that the token and message bodies never
+reach the logs. Message text carries magic-link and invite tokens, so it must
+never be logged.

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+// Auto-generated by emdash-plugin build. Do not edit.
+import type { PluginDescriptor } from "@premium-cms/emdash";
+
+declare const descriptor: PluginDescriptor;
+export default descriptor;

package/dist/index.mjs

@@ -0,0 +1,30 @@
+// Auto-generated by emdash-plugin build. Do not edit.
+// Source: emdash-plugin.jsonc + package.json
+//
+// Default-exports a sandboxed plugin descriptor. Pass it directly into
+// emdash's `plugins:` or `sandboxed:` array — no factory call needed.
+
+/** @type {import("@premium-cms/emdash").PluginDescriptor} */
+const descriptor = Object.freeze({
+	"id": "cloudflare-email-byo",
+	"version": "0.1.0",
+	"format": "standard",
+	"entrypoint": "@premium-cms/plugin-cloudflare-email-byo/sandbox",
+	"capabilities": [
+		"hooks.email-transport:register",
+		"network:request"
+	],
+	"allowedHosts": [
+		"api.cloudflare.com"
+	],
+	"storage": {},
+	"adminPages": [
+		{
+			"path": "/settings",
+			"label": "Email (own Cloudflare)",
+			"icon": "mail"
+		}
+	]
+});
+
+export default descriptor;

package/dist/manifest.json

@@ -0,0 +1,47 @@
+{
+  "id": "cloudflare-email-byo",
+  "version": "0.1.0",
+  "declaredAccess": {
+    "network": {
+      "request": {
+        "allowedHosts": [
+          "api.cloudflare.com"
+        ]
+      }
+    },
+    "email": {
+      "transport": {}
+    }
+  },
+  "capabilities": [
+    "hooks.email-transport:register",
+    "network:request"
+  ],
+  "allowedHosts": [
+    "api.cloudflare.com"
+  ],
+  "storage": {},
+  "hooks": [
+    "plugin:install",
+    {
+      "name": "email:deliver",
+      "exclusive": true
+    }
+  ],
+  "routes": [
+    "admin",
+    "settings",
+    "settings/save",
+    "test"
+  ],
+  "admin": {
+    "pages": [
+      {
+        "path": "/settings",
+        "label": "Email (own Cloudflare)",
+        "icon": "mail"
+      }
+    ],
+    "widgets": []
+  }
+}

package/dist/plugin.d.mts

@@ -0,0 +1,7 @@
+import { SandboxedPlugin } from "@premium-cms/emdash/plugin";
+
+//#region src/plugin.d.ts
+declare const plugin: SandboxedPlugin;
+//#endregion
+export { plugin as default };
+//# sourceMappingURL=plugin.d.mts.map

package/dist/plugin.mjs

@@ -0,0 +1,4 @@
+const e=`settings:`,t=/^[0-9a-f]{32}$/;function n(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function r(e,t=``){return typeof e==`string`?e:t}function i(e){let t=e.indexOf(`@`);return t>0&&t<e.length-1&&!/\s/.test(e)}async function a(t){let n={accountId:``,fromAddress:``,fromName:``,replyTo:``,apiToken:``};try{let n=await t.kv.list(e),i={};for(let t of n)i[t.key.replace(e,``)]=t.value;return{accountId:r(i.accountId).trim(),fromAddress:r(i.fromAddress).trim(),fromName:r(i.fromName).trim(),replyTo:r(i.replyTo).trim(),apiToken:r(i.apiToken)}}catch(e){return t.log.error(`Failed to read settings`,e),n}}function o(e){let n=[];return e.accountId?t.test(e.accountId)||n.push(`a valid account ID (32 hex characters)`):n.push(`account ID`),e.apiToken||n.push(`API token`),e.fromAddress?i(e.fromAddress)||n.push(`a valid sender address`):n.push(`sender address`),n.length===0?{ok:!0}:{ok:!1,missing:n}}function s(e){return e?e.length<=8?`••••••••`:`••••••••${e.slice(-4)}`:``}function c(e,t){if(e===200&&t?.success!==!1){let e=t?.result?.permanent_bounces??[];return e.length>0?`permanently bounced: ${e.join(`, `)}`:null}let n=(t?.errors??[]).map(e=>e.code?`${e.code}: ${e.message??``}`:e.message??``).filter(Boolean).join(`; `)||`HTTP ${e}`;switch(e){case 401:case 403:return`authentication rejected (${n}) — check the API token has email sending permission`;case 400:return`request rejected (${n}) — check the sender domain is onboarded for Email Sending`;case 429:return`rate limited (${n}) — retryable`;default:return e>=500?`Cloudflare error (${n}) — retryable`:n}}async function l(e,t,n){if(!e.http)throw Error("[cloudflare-email-byo] ctx.http is unavailable — the plugin needs the `network:request` capability.");let r={to:n.to,from:t.fromName?{address:t.fromAddress,name:t.fromName}:{address:t.fromAddress},subject:n.subject,text:n.text};n.html&&(r.html=n.html),t.replyTo&&(r.reply_to=t.replyTo);let i=await e.http.fetch(`https://api.cloudflare.com/client/v4/accounts/${t.accountId}/email/sending/send`,{method:`POST`,headers:{Authorization:`Bearer ${t.apiToken}`,"Content-Type":`application/json`},body:JSON.stringify(r)}),a=null;try{a=await i.json()}catch{}let o=c(i.status,a);if(o)throw Error(`[cloudflare-email-byo] send failed for ${n.to} — ${o}`);e.log.info(`email delivered via the site's own Cloudflare account`,{to:n.to,subject:n.subject,accountId:t.accountId})}const u={hooks:{"plugin:install":async(e,t)=>{t.log.info(`Cloudflare Email (own account) installed — add credentials on its settings page, then select it under Settings → Email`)},"email:deliver":{exclusive:!0,handler:async(e,t)=>{let n=await a(t),r=o(n);if(!r.ok)throw Error(`[cloudflare-email-byo] not configured — missing ${r.missing.join(`, `)}. Add them on the plugin's settings page.`);await l(t,n,e.message)}}},routes:{admin:{handler:async(e,t)=>{let n=e.input;return n.type===`page_load`&&n.page===`/settings`?p(t):n.type===`form_submit`&&n.action_id===`save_settings`?p(t,await d(t,n.values??{})):n.type===`block_action`&&n.action_id===`send_test`?p(t,await f(t)):{blocks:[]}}},settings:{handler:async(e,t)=>{let n=await a(t),r=o(n);return{accountId:n.accountId,fromAddress:n.fromAddress,fromName:n.fromName,replyTo:n.replyTo,apiToken:s(n.apiToken??``),configured:r.ok,missing:r.ok?[]:r.missing}}},"settings/save":{handler:async(e,t)=>{try{return{success:!0,note:await d(t,n(e.input)?e.input:{}),configured:o(await a(t)).ok}}catch(e){return t.log.error(`Failed to save settings`,e),{success:!1,error:String(e)}}}},test:{handler:async(e,t)=>({message:await f(t)})}}};async function d(t,n){if(typeof n.accountId==`string`&&await t.kv.set(`${e}accountId`,n.accountId.trim().toLowerCase()),typeof n.fromAddress==`string`&&await t.kv.set(`${e}fromAddress`,n.fromAddress.trim()),typeof n.fromName==`string`&&await t.kv.set(`${e}fromName`,n.fromName.trim()),typeof n.replyTo==`string`&&await t.kv.set(`${e}replyTo`,n.replyTo.trim()),typeof n.apiToken==`string`){let r=n.apiToken.trim();if(r===`clear`)return await t.kv.set(`${e}apiToken`,``),`API token cleared.`;if(r)return await t.kv.set(`${e}apiToken`,r),`API token updated.`}}async function f(e){let t=await a(e),n=o(t);if(!n.ok)return`Cannot send a test — missing ${n.missing.join(`, `)}.`;try{return await l(e,t,{to:t.fromAddress,subject:`Test email from your site`,text:`This is a test from the Cloudflare Email (own account) provider.
+
+If you received it, transactional email is sending through your own Cloudflare account.`}),`Test sent to ${t.fromAddress}.`}catch(e){return String(e instanceof Error?e.message:e)}}async function p(e,t){try{let n=await a(e),r=o(n),i=!!n.apiToken,c=[{type:`header`,text:`Email from your own Cloudflare account`},{type:`context`,text:`Transactional email (sign-in links, invites, notifications) is sent through your Cloudflare account instead of the platform's.`},{type:`divider`},{type:`section`,text:r.ok?`Ready — sending as ${n.fromAddress} from account ${n.accountId}.`:`Not sending yet — missing ${r.missing.join(`, `)}.`}];return t&&c.push({type:`context`,text:t}),c.push({type:`divider`},{type:`form`,block_id:`cloudflare-email-byo-settings`,fields:[{type:`text_input`,action_id:`accountId`,label:`Cloudflare account ID`,placeholder:`32 hex characters, from the dashboard sidebar`,initial_value:n.accountId},{type:`secret_input`,action_id:`apiToken`,label:i?`API token (stored: ${s(n.apiToken??``)} — leave blank to keep, type "clear" to remove)`:`API token (needs email sending permission)`},{type:`text_input`,action_id:`fromAddress`,label:`Send from`,placeholder:`cms@mail.yourdomain.com`,initial_value:n.fromAddress},{type:`text_input`,action_id:`fromName`,label:`Sender name`,placeholder:`Your Site`,initial_value:n.fromName},{type:`text_input`,action_id:`replyTo`,label:`Reply-To (optional)`,initial_value:n.replyTo}],submit:{label:`Save`,action_id:`save_settings`}},{type:`actions`,elements:[{type:`button`,text:`Send test email`,action_id:`send_test`,style:`primary`}]},{type:`divider`},{type:`context`,text:`The sending domain must be onboarded for Email Sending in your own Cloudflare account, and the token needs email sending permission. Once saved, choose this provider under Settings → Email.`}),{blocks:c}}catch(t){return e.log.error(`Failed to build settings page`,t),{blocks:[{type:`context`,text:`Failed to load email settings.`}]}}}export{u as default};
+//# sourceMappingURL=plugin.mjs.map

package/emdash-plugin.jsonc

@@ -0,0 +1,33 @@
+{
+	"$schema": "../../node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",
+
+	"slug": "cloudflare-email-byo",
+	// See plugins/premium-starter — must resolve for real before `publish`.
+	"publisher": "plugins.premium-cms.com",
+
+	"license": "MIT",
+	"author": { "name": "PremiumCMS" },
+	"security": {
+		"url": "https://github.com/MahmoodKhalil57/premium-cms-plugins/security/advisories/new",
+	},
+	"description": "Send transactional email through the site owner's own Cloudflare account, using an API token entered in the admin.",
+	"keywords": ["premiumcms", "email", "cloudflare", "transactional", "byo-credentials"],
+
+	// ── Trust contract ────────────────────────────────────────────────
+	// `hooks.email-transport:register` is what allows registering the
+	// exclusive `email:deliver` hook — without it the hook is silently
+	// skipped at registration and the plugin appears to do nothing.
+	//
+	// `network:request` (rather than `network:request:unrestricted`)
+	// restricts ctx.http to `allowedHosts`. The owner's Cloudflare API
+	// token is the most sensitive value this plugin holds, so egress is
+	// pinned to the one host that token is valid for: a bug or a bad
+	// settings value cannot post it anywhere else.
+	"capabilities": ["hooks.email-transport:register", "network:request"],
+	"allowedHosts": ["api.cloudflare.com"],
+	"storage": {},
+
+	"admin": {
+		"pages": [{ "path": "/settings", "label": "Email (own Cloudflare)", "icon": "mail" }],
+	},
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@premium-cms/plugin-cloudflare-email-byo",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Send email through the site owner's own Cloudflare account",
+  "main": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./sandbox": "./dist/plugin.mjs"
+  },
+  "files": [
+    "dist",
+    "emdash-plugin.jsonc"
+  ],
+  "scripts": {
+    "build": "emdash-plugin build",
+    "dev": "emdash-plugin dev",
+    "bundle": "emdash-plugin bundle",
+    "validate": "emdash-plugin validate .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@premium-cms/emdash": ">=0.35.0"
+  },
+  "devDependencies": {
+    "@premium-cms/plugin-cli": "^0.8.1",
+    "@premium-cms/plugin-types": "^0.3.0",
+    "@premium-cms/emdash": "^0.35.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}