alchemy 0.3.1 → 0.4.1

package/src/cloudflare/account-api-token.ts

@@ -0,0 +1,365 @@
+import { alchemy } from "../alchemy";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { Secret } from "../secret";
+import { sha256 } from "../util/sha256";
+import { createCloudflareApi } from "./api";
+
+/**
+ * Permission group for a token policy
+ */
+export interface TokenPolicyPermissionGroup {
+  /**
+   * ID of the permission group
+   */
+  id: string;
+
+  /**
+   * Optional metadata for the permission group
+   */
+  meta?: Record<string, any>;
+}
+
+/**
+ * Policy that defines what the token can access
+ */
+export interface TokenPolicy {
+  /**
+   * Effect of the policy
+   */
+  effect: "allow" | "deny";
+
+  /**
+   * Permission groups to include in the policy
+   */
+  permissionGroups: TokenPolicyPermissionGroup[];
+
+  /**
+   * Resources the policy applies to
+   */
+  resources: Record<string, string>;
+}
+
+/**
+ * Condition for token usage (e.g., IP restrictions)
+ */
+export interface TokenCondition {
+  /**
+   * IP address conditions
+   */
+  requestIp?: {
+    /**
+     * IP ranges to allow
+     */
+    in?: string[];
+
+    /**
+     * IP ranges to deny
+     */
+    notIn?: string[];
+  };
+}
+
+/**
+ * Properties for creating or updating an Account API Token
+ */
+export interface AccountApiTokenProps {
+  /**
+   * Name of the token
+   */
+  name: string;
+
+  /**
+   * Policies that define what the token can access
+   */
+  policies: TokenPolicy[];
+
+  /**
+   * Optional expiration date for the token (ISO format)
+   */
+  expiresOn?: string;
+
+  /**
+   * Optional "not before" date (token is not valid before this date) (ISO format)
+   */
+  notBefore?: string;
+
+  /**
+   * Optional conditions for token use (like IP restrictions)
+   */
+  condition?: TokenCondition;
+}
+
+/**
+ * Cloudflare API token format as returned by the API
+ */
+interface CloudflareApiToken {
+  id: string;
+  name: string;
+  status: string;
+  policies: {
+    effect: "allow" | "deny";
+    permission_groups: {
+      id: string;
+      meta: Record<string, any>;
+    }[];
+    resources: Record<string, string>;
+  }[];
+  expires_on?: string;
+  not_before?: string;
+  condition?: {
+    request_ip?: {
+      in?: string[];
+      not_in?: string[];
+    };
+  };
+  value?: string;
+}
+
+/**
+ * Output returned after Account API Token creation/update
+ */
+export interface AccountApiToken
+  extends Resource<"cloudflare::AccountApiToken">,
+    AccountApiTokenProps {
+  /**
+   * The ID of the token
+   *
+   * Equiv. to ACCESS_KEY_ID
+   */
+  id: string;
+
+  /**
+   * Status of the token
+   */
+  status: string;
+
+  /**
+   * Actual token value (only available on creation)
+   * Stored as a Secret for security
+   *
+   * Equiv. to SECRET_ACCESS_KEY
+   */
+  value?: Secret;
+
+  /**
+   * Access key ID for the token
+   *
+   * An alias of {@link id}
+   */
+  accessKeyId: string;
+
+  /**
+   * Secret access key for the token
+   *
+   * The SHA-256 hash of the token {@link value}
+   *
+   * @see https://developers.cloudflare.com/r2/api/tokens/#get-s3-api-credentials-from-an-api-token
+   */
+  secretAccessKey: string;
+}
+
+/**
+ * Creates a Cloudflare Account API Token with specified permissions.
+ *
+ * @see https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/methods/create/
+ *
+ * @example
+ * // First, fetch all permission groups
+ * const permissions = await PermissionGroups("cloudflare-permissions", {
+ *   accountId: cfAccountId,
+ * });
+ *
+ * // Create a token with read-only permissions for specific zones
+ * const readOnlyToken = await AccountApiToken("readonly-token", {
+ *   name: "Readonly Zone Token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: [
+ *         { id: permissions["Zone Read"].id },
+ *         { id: permissions["Analytics Read"].id }
+ *       ],
+ *       resources: {
+ *         "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "*",
+ *         "com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "*"
+ *       }
+ *     }
+ *   ],
+ *   expiresOn: "2024-12-31T23:59:59Z"
+ * });
+ *
+ * @example
+ * // Create a token with time and IP restrictions
+ * const restrictedToken = await AccountApiToken("restricted-token", {
+ *   name: "Restricted Access Token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: [
+ *         { id: permissions["Worker Routes Edit"].id }
+ *       ],
+ *       resources: {
+ *         "com.cloudflare.api.account.worker.route.*": "*"
+ *       }
+ *     }
+ *   ],
+ *   notBefore: "2023-01-01T00:00:00Z",
+ *   expiresOn: "2023-12-31T23:59:59Z",
+ *   condition: {
+ *     requestIp: {
+ *       in: ["192.168.1.0/24", "10.0.0.0/8"],
+ *       notIn: ["192.168.1.100/32"]
+ *     }
+ *   }
+ * });
+ */
+export const AccountApiToken = Resource(
+  "cloudflare::AccountApiToken",
+  async function (
+    this: Context<AccountApiToken>,
+    id: string,
+    props: AccountApiTokenProps
+  ): Promise<AccountApiToken> {
+    // Create Cloudflare API client with automatic account discovery
+    const api = await createCloudflareApi();
+
+    if (this.phase === "delete") {
+      // Delete token if we have an ID
+      if (this.output?.id) {
+        try {
+          const deleteResponse = await api.delete(
+            `/accounts/${api.accountId}/tokens/${this.output.id}`
+          );
+
+          if (!deleteResponse.ok && deleteResponse.status !== 404) {
+            const errorData: any = await deleteResponse.json().catch(() => ({
+              errors: [{ message: deleteResponse.statusText }],
+            }));
+            console.error(`Error deleting token '${props.name}':`, errorData);
+          }
+        } catch (error) {
+          console.error(`Error deleting token '${props.name}':`, error);
+        }
+      }
+
+      // Return destroyed state
+      return this.destroy();
+    }
+
+    // Transform our properties to API format
+    const apiPayload = {
+      name: props.name,
+      policies: props.policies.map((policy) => ({
+        effect: policy.effect,
+        permission_groups: policy.permissionGroups.map((pg) => ({
+          id: pg.id,
+          meta: pg.meta || {},
+        })),
+        resources: policy.resources,
+      })),
+      // Format dates for Cloudflare API (removing milliseconds)
+      ...(props.expiresOn
+        ? { expires_on: formatCloudflareDate(props.expiresOn) }
+        : {}),
+      ...(props.notBefore
+        ? { not_before: formatCloudflareDate(props.notBefore) }
+        : {}),
+      ...(props.condition
+        ? {
+            condition: {
+              request_ip: props.condition.requestIp
+                ? {
+                    in: props.condition.requestIp.in || [],
+                    not_in: props.condition.requestIp.notIn || [],
+                  }
+                : undefined,
+            },
+          }
+        : {}),
+    };
+
+    /**
+     * Formats a date string for Cloudflare API by removing milliseconds
+     * Converts from "2023-01-01T00:00:00.000Z" to "2023-01-01T00:00:00Z"
+     */
+    function formatCloudflareDate(dateStr: string): string {
+      return dateStr.replace(/\.\d{3}Z$/, "Z");
+    }
+
+    let response;
+    let tokenValue;
+
+    if (this.phase === "update" && this.output?.id) {
+      // Update existing token
+      response = await api.put(
+        `/accounts/${api.accountId}/tokens/${this.output.id}`,
+        apiPayload
+      );
+    } else {
+      // Create new token
+      response = await api.post(
+        `/accounts/${api.accountId}/tokens`,
+        apiPayload
+      );
+    }
+
+    if (!response.ok) {
+      const errorData: any = await response.json().catch(() => ({
+        errors: [{ message: response.statusText }],
+      }));
+
+      throw new Error(
+        `Error ${this.phase === "update" ? "updating" : "creating"} token '${props.name}': ${
+          errorData.errors?.[0]?.message || response.statusText
+        }`
+      );
+    }
+
+    const result: { result: CloudflareApiToken } = await response.json();
+    const tokenData = result.result;
+
+    if (tokenData.value) {
+      tokenValue = alchemy.secret(tokenData.value);
+    } else {
+      if (!this.output?.value) {
+        throw new Error(
+          `Token '${props.name}' was created but we have no record of its value. Try deleting and recreating the token.`
+        );
+      }
+      tokenValue = this.output?.value;
+    }
+
+    // Transform API response to our format
+    return this({
+      id: tokenData.id,
+      name: tokenData.name,
+      status: tokenData.status,
+      policies: tokenData.policies.map((policy) => ({
+        effect: policy.effect,
+        permissionGroups: policy.permission_groups.map((pg) => ({
+          id: pg.id,
+          meta: pg.meta,
+        })),
+        resources: policy.resources,
+      })),
+      ...(tokenData.expires_on ? { expiresOn: tokenData.expires_on } : {}),
+      ...(tokenData.not_before ? { notBefore: tokenData.not_before } : {}),
+      ...(tokenData.condition
+        ? {
+            condition: {
+              requestIp: tokenData.condition.request_ip
+                ? {
+                    in: tokenData.condition.request_ip.in || [],
+                    notIn: tokenData.condition.request_ip.not_in || [],
+                  }
+                : undefined,
+            },
+          }
+        : {}),
+      value: tokenValue,
+      accessKeyId: tokenData.id,
+      secretAccessKey: sha256(tokenValue.unencrypted),
+    });
+  }
+);

package/src/cloudflare/api.ts

@@ -1,3 +1,4 @@
+import type { Secret } from "../secret";
 import { type CloudflareAuthOptions, getCloudflareHeaders } from "./auth";
 
 /**
@@ -7,7 +8,7 @@ export interface CloudflareApiOptions {
   /**
    * API Key to use (overrides CLOUDFLARE_API_KEY env var)
    */
-  apiKey?: string;
+  apiKey?: Secret;
 
   /**
    * Account ID to use (overrides CLOUDFLARE_ACCOUNT_ID env var)
@@ -35,6 +36,65 @@ interface CloudflareAccount {
   name: string;
 }
 
+/**
+ * Custom error class for Cloudflare API errors
+ * Includes HTTP status information from the Response
+ */
+export class CloudflareApiError extends Error {
+  /**
+   * HTTP status code
+   */
+  status: number;
+
+  /**
+   * HTTP status text
+   */
+  statusText: string;
+
+  /**
+   * Raw error data from the API
+   */
+  errorData?: any;
+
+  /**
+   * Create a new CloudflareApiError
+   */
+  constructor(message: string, response: Response, errorData?: any) {
+    super(message);
+    this.name = "CloudflareApiError";
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.errorData = errorData;
+
+    // Ensure instanceof works correctly
+    Object.setPrototypeOf(this, CloudflareApiError.prototype);
+  }
+}
+
+/**
+ * Helper function to handle API errors
+ *
+ * @param response The fetch Response object
+ * @param action The action being performed (e.g., "creating", "deleting")
+ * @param resourceType The type of resource being acted upon (e.g., "R2 bucket", "Worker")
+ * @param resourceName The name/identifier of the specific resource
+ * @returns Never returns - always throws an error
+ */
+export async function handleApiError(
+  response: Response,
+  action: string,
+  resourceType: string,
+  resourceName: string
+): Promise<never> {
+  const json: any = await response.json();
+  console.log(json);
+  const errorData: any = json.errors || [{ message: response.statusText }];
+
+  const errorMessage = `Error ${action} ${resourceType} '${resourceName}': ${errorData.errors?.[0]?.message || response.statusText}`;
+
+  throw new CloudflareApiError(errorMessage, response, errorData);
+}
+
 /**
  * Creates a CloudflareApi instance with automatic account ID discovery if not provided
  *
@@ -42,24 +102,33 @@ interface CloudflareAccount {
  * @returns Promise resolving to a CloudflareApi instance
  */
 export async function createCloudflareApi(
-  options: CloudflareApiOptions = {},
+  options: CloudflareApiOptions = {}
 ): Promise<CloudflareApi> {
   try {
     return new CloudflareApi({
       ...options,
-      accountId:
-        options.accountId ||
-        process.env.CLOUDFLARE_ACCOUNT_ID ||
-        (await fetchAccountId()),
+      accountId: await CloudflareAccountId(options),
     });
   } catch (error) {
     console.error("Error during Cloudflare account ID discovery:", error);
     throw new Error(
-      "Failed to automatically discover Cloudflare account ID. Please provide an account ID explicitly or ensure your API token/key has sufficient permissions.",
+      "Failed to automatically discover Cloudflare account ID. Please provide an account ID explicitly or ensure your API token/key has sufficient permissions."
     );
   }
 }
 
+export type CloudflareAccountId = string & {
+  readonly __brand: "CloudflareAccountId";
+};
+
+export async function CloudflareAccountId(
+  options: CloudflareApiOptions = {}
+): Promise<CloudflareAccountId> {
+  return (options.accountId ||
+    process.env.CLOUDFLARE_ACCOUNT_ID ||
+    (await fetchAccountId())) as CloudflareAccountId;
+}
+
 /**
  * Cloudflare API client using raw fetch
  */
@@ -93,10 +162,12 @@ export class CloudflareApi {
     this.baseUrl = "https://api.cloudflare.com/client/v4";
 
     const apiKey =
-      options.apiKey || process.env.CLOUDFLARE_API_KEY || undefined;
+      options.apiKey?.unencrypted ||
+      process.env.CLOUDFLARE_API_KEY ||
+      undefined;
     if (!apiKey) {
       throw new Error(
-        "No API key provided. Use createCloudflareApi() instead for automatic account discovery.",
+        "No API key provided. Use createCloudflareApi() instead for automatic account discovery."
       );
     }
     this.apiKey = apiKey;
@@ -104,7 +175,7 @@ export class CloudflareApi {
     this.email = options.email || process.env.CLOUDFLARE_EMAIL;
     if (!this.email) {
       throw new Error(
-        "No email provided. Use createCloudflareApi() instead for automatic account discovery.",
+        "No email provided. Use createCloudflareApi() instead for automatic account discovery."
       );
     }
 
@@ -113,7 +184,7 @@ export class CloudflareApi {
       options.accountId || process.env.CLOUDFLARE_ACCOUNT_ID || "";
     if (!this.accountId) {
       throw new Error(
-        "No account ID provided. Use createCloudflareApi() instead for automatic account discovery.",
+        "No account ID provided. Use createCloudflareApi() instead for automatic account discovery."
       );
     }
 
@@ -146,7 +217,7 @@ export class CloudflareApi {
     // Get auth headers (async now)
     const authHeaders = await getCloudflareHeaders(
       contentType,
-      this.authOptions,
+      this.authOptions
     );
 
     // Combine all headers
@@ -195,7 +266,7 @@ export class CloudflareApi {
   async post(
     path: string,
     body: any,
-    init: RequestInit = {},
+    init: RequestInit = {}
   ): Promise<Response> {
     const requestBody =
       body instanceof FormData
@@ -212,7 +283,7 @@ export class CloudflareApi {
   async put(
     path: string,
     body: any,
-    init: RequestInit = {},
+    init: RequestInit = {}
   ): Promise<Response> {
     const requestBody = body instanceof FormData ? body : JSON.stringify(body);
     return this.fetch(path, { ...init, method: "PUT", body: requestBody });
@@ -224,7 +295,7 @@ export class CloudflareApi {
   async patch(
     path: string,
     body: any,
-    init: RequestInit = {},
+    init: RequestInit = {}
   ): Promise<Response> {
     return this.fetch(path, {
       ...init,
@@ -264,7 +335,7 @@ async function fetchAccountId(): Promise<string> {
     }));
 
     throw new Error(
-      `Error fetching Cloudflare accounts: ${errorData.errors?.[0]?.message || response.statusText}`,
+      `Error fetching Cloudflare accounts: ${errorData.errors?.[0]?.message || response.statusText}`
     );
   }
 
@@ -273,7 +344,7 @@ async function fetchAccountId(): Promise<string> {
 
   if (!accounts || accounts.length === 0) {
     throw new Error(
-      "No Cloudflare accounts found. Check your API token/key permissions.",
+      "No Cloudflare accounts found. Check your API token/key permissions."
     );
   }