Cloudflare

Package cloudflare is your Cloudflare account, managed from Hanzo: zones, Pages, Workers, Workers AI, R2, KV and D1.

Specification

/v1/cloudflare is an org's own Cloudflare account, managed from Hanzo: zones and their analytics, Pages, Workers, Workers AI, R2, KV and D1, all driven through the API token that org connected. It is implemented in hanzoai/cloud apps/cloudflare. This HIP states the two separations that define it — how you connected is the integrations plane, what you manage is this plane; and every call rides the org's own token, so the platform never reaches Cloudflare with a global credential.

Motivation

Connecting a provider and managing its resources are different concerns with different lifetimes: a connection is made once and custodied, resources are driven daily. Braiding them puts credential custody inside every resource handler. The split gives each one owner: /v1/integrations/cloudflare/* connects (HIP-0126), /v1/cloudflare/* manages (apps/cloudflare/cloudflare.go:7-13).

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.

§1 The token, and the one door to it

The capability owns no store. Its only state is the per-org API token, sealed in KMS at /orgs/{org}/integrations/cloudflare/api_token and read in-process through the one custody seam integrations.TokenFor (apps/cloudflare/cloudflare.go:24-27) — the same coordinate both the apikey and OAuth connect paths seal to, and that DNS reads. The token MUST ride only the Authorization header of the outbound request to https://api.cloudflare.com/client/v4 (apps/cloudflare/cloudflare.go:92); it is never logged, echoed in an error, or stored by this subsystem.

Fail-closed: an org that has not connected, an unmounted integrations plane, or a KMS that is not Ready each answer 503 — never another org's data and never a silent success (apps/cloudflare/cloudflare.go:39-41).

§2 Tenancy

Every handler resolves the org from the validated principal (principal.Org, HIP-0026), never a body or query field, and that org is the only input to token custody — so a request can only ever address its own org's Cloudflare account. No validated principal means 403; a non-SuperAdmin bearer has its org pinned by the identity boundary, so it cannot name another (apps/cloudflare/cloudflare.go:22-34).

§3 The addresses

Everything is under /v1/cloudflare: zones (list, detail, analytics, purge), pages/projects (with deployments and domains), workers/scripts (with subdomain and zone routes), r2/buckets, kv/namespaces (with values), d1/databases (with query), and ai/run/{model}. The resource operations are typed; ai/run is the one relay — the model's body passes through, bounded by maxAIBody, and the wire test (apps/cloudflare/relay_wire_test.go) holds it.

§4 Money

The capability is metered (plugin/cloudflare/main.go:21), and Workers AI is the one operation that debits: an /ai/run is inference, so it meters through the same usage spine as every model call, at the thin BYO fee — the org's own token already paid Cloudflare for the compute. The gate runs before any Cloudflare contact, on a floored estimate (BYOInferenceFeeMicros, so gateCents ≥ 1 even for a modality whose token estimate is 0), and the exact debit lands after the call on the tokens the model reported (apps/cloudflare/ai.go:112-160). The payer is principal.Ledger; MeterUsage records under provider ai, service workers-ai, so this spend sums with LLM spend on the same axis. Everything else is passthrough on the org's own account and costs nothing here.

§5 Events, telemetry, stage, upstreams

It publishes no events on the bus. Beyond the request span, /ai/run emits one gen_ai span on the same plane as every model call, with system cloudflare and per-model attribution (apps/cloudflare/ai.go:129-131). Its stage is ga: it is platform infrastructure — the sibling of /v1/dns and /v1/domain — not a vertical application. It derives from no upstream; it speaks Cloudflare's public REST API v4 directly as a wire fact, with no vendored SDK.

Rationale

The alternative to per-org tokens is a platform-level Cloudflare credential with tenancy enforced by our own bookkeeping. That is one secret whose compromise is every org's infrastructure, and it makes the platform the customer of record for assets that are the org's. Deriving the token path from the validated org makes cross-org reach structurally impossible rather than policed — the coordinate for another tenant's token is never constructed.

Security Considerations

The wrong implementation here hands an attacker another org's Cloudflare account: DNS, live sites, storage, and edge code — enough to serve malware from a victim's domain. The org-to-token derivation in §2 is the whole defense, and the fee gate in §4 is the second: without it, a relay to a paid inference API is a free-compute primitive billed to nobody. Both fail closed, and a frozen or over-cap org is refused before Cloudflare is ever contacted — no discovery, no run (apps/cloudflare/ai.go:113-120).

Four surfaces

Quickstart

export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/cloudflare/zones, operation get_cloudflare_zones:

hanzo cloudflare zones list

import { Configuration, CloudflareApi } from 'hanzoai';

const api = new CloudflareApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getCloudflareZones();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import CloudflareApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = CloudflareApi(client).get_cloudflare_zones()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.CloudflareAPI.GetCloudflareZones(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, cloudflare_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = cloudflare_api::get_cloudflare_zones(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.CloudflareApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new CloudflareApi(client).getCloudflareZones();

curl https://api.hanzo.ai/v1/cloudflare/zones \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_cloudflare_d1_databases"
         }
       }
     }'

Answers 200 — ok.

Endpoints

All Hanzo APIs · Interactive reference