alchemy 0.3.0 → 0.4.0

package/lib/alchemy.js

@@ -13,11 +13,17 @@ export const alchemy = _alchemy;
 function _alchemy(...args) {
     if (typeof args[0] === "string") {
         const [appName, options] = args;
-        return scope(undefined, {
+        const root = scope(undefined, {
             ...options,
             appName,
             stage: options?.stage,
         });
+        if (options?.phase === "destroy") {
+            return destroy(root).finally(() => {
+                process.exit(0);
+            });
+        }
+        return root;
     }
     else {
         const [template, ...values] = args;
@@ -33,6 +39,17 @@ function _alchemy(...args) {
                 if (typeof value === "string") {
                     return indent + value;
                 }
+                else if (value === null) {
+                    return "null";
+                }
+                else if (value === undefined) {
+                    return "undefined";
+                }
+                else if (typeof value === "number" ||
+                    typeof value === "boolean" ||
+                    typeof value === "bigint") {
+                    return value.toString();
+                }
                 else if (value instanceof Promise) {
                     return resolve(await value);
                 }
@@ -53,9 +70,26 @@ function _alchemy(...args) {
                 else if (Array.isArray(value)) {
                     return (await Promise.all(value.map(async (value, i) => `${i}. ${await resolve(value)}`))).join("\n");
                 }
+                else if (typeof value === "object" &&
+                    typeof value.path === "string") {
+                    if (typeof value.content === "string") {
+                        appendices[value.path] = value.content;
+                        return `[${path.basename(value.path)}](${value.path})`;
+                    }
+                    else {
+                        appendices[value.path] = await fs.readFile(value.path, "utf-8");
+                        return `[${path.basename(value.path)}](${value.path})`;
+                    }
+                }
+                else if (typeof value === "object") {
+                    return (await Promise.all(Object.entries(value).map(async ([key, value]) => {
+                        return `* ${key}: ${await resolve(value)}`;
+                    }))).join("\n");
+                }
                 else {
                     // TODO: support other types
-                    throw new Error(`Unsupported value type: ${JSON.stringify(value)}`);
+                    console.log(value);
+                    throw new Error(`Unsupported value type: ${value}`);
                 }
             }));
             // Construct the string template by joining template parts with interpolated values
@@ -90,6 +124,7 @@ _alchemy.destroy = destroy;
 _alchemy.run = run;
 _alchemy.scope = scope;
 _alchemy.secret = secret;
+_alchemy.env = env;
 /**
  * Enter a new scope synchronously.
  *
@@ -104,7 +139,10 @@ _alchemy.secret = secret;
  *   apiKey: alchemy.secret(process.env.API_KEY)
  * });
  */
-function scope(id, options) {
+function scope(id, options
+// TODO: maybe we want to allow using _ = await alchemy.scope(import.meta)
+// | [meta: ImportMeta]
+) {
     const scope = new Scope({
         ...options,
         appName: options?.appName,
@@ -150,3 +188,23 @@ async function run(...args) {
         await scope.finalize();
     }
 }
+export async function env(name, value, error) {
+    if (value !== undefined) {
+        return value;
+    }
+    else if (typeof process !== undefined) {
+        // we are in a node environment
+        return process.env[name];
+    }
+    else {
+        // we are in a browser environment
+        try {
+            const { env } = await import("cloudflare:workers");
+            if (name in env) {
+                return env[name];
+            }
+        }
+        catch (error) { }
+    }
+    throw new Error(error ?? `Environment variable ${name} is not set`);
+}

package/lib/apply.js

@@ -1,8 +1,7 @@
 import { alchemy } from "./alchemy";
 import { context } from "./context";
 import { PROVIDERS, } from "./resource";
-import { Secret } from "./secret";
-import { serialize } from "./util/serde";
+import { serialize } from "./serde";
 export async function apply(resource, props, options) {
     const scope = resource.Scope;
     try {
@@ -36,20 +35,27 @@ export async function apply(resource, props, options) {
         const alwaysUpdate = options?.alwaysUpdate ?? provider.options?.alwaysUpdate ?? false;
         // Skip update if inputs haven't changed and resource is in a stable state
         if (state.status === "created" || state.status === "updated") {
-            const oldProps = JSON.stringify(state.props, (_, value) => value instanceof Secret
-                ? {
-                    "@secret": value.unencrypted,
-                }
-                : value, 2);
-            const newProps = JSON.stringify(await serialize(scope, props, {
+            const oldProps = await serialize(scope, state.props, {
+                encrypt: false,
+            });
+            const newProps = await serialize(scope, props, {
                 encrypt: false,
-            }), null, 2);
-            if (oldProps === newProps && alwaysUpdate !== true) {
+            });
+            if (JSON.stringify(oldProps) === JSON.stringify(newProps) &&
+                alwaysUpdate !== true) {
                 if (!quiet) {
-                    console.log(`Skip:    "${resource.FQN}" (no changes)`);
+                    // console.log(`Skip:    "${resource.FQN}" (no changes)`);
                 }
                 return state.output;
             }
+            const diff = await import("diff");
+            const yaml = await import("yaml");
+            const old = yaml.stringify(oldProps);
+            const news = yaml.stringify(newProps);
+            const patch = diff.createPatch(resource.ID, old, news);
+            // console.log(patch);
+            // if (resource.ID === "what-is-alchemy") {
+            // }
         }
         const phase = state.status === "creating" ? "create" : "update";
         state.status = phase === "create" ? "creating" : "updating";
@@ -98,6 +104,7 @@ export async function apply(resource, props, options) {
         return output;
     }
     catch (error) {
+        console.error(new Error().stack);
         scope.fail();
         throw error;
     }

package/lib/aws/account-id.d.ts

@@ -1,4 +1,7 @@
+export type AccountId = string & {
+    readonly __brand: "AccountId";
+};
 /**
  * Helper to get the current AWS account ID
  */
-export declare function getAccountId(): Promise<string>;
+export declare function AccountId(): Promise<AccountId>;

package/lib/aws/account-id.js

@@ -3,7 +3,7 @@ const sts = new STSClient({});
 /**
  * Helper to get the current AWS account ID
  */
-export async function getAccountId() {
+export async function AccountId() {
     const identity = await sts.send(new GetCallerIdentityCommand({}));
     return identity.Account;
 }

package/lib/aws/credentials.d.ts

@@ -0,0 +1,5 @@
+import type { Secret } from "../secret";
+export interface AwsCredentials {
+    accessKeyId: Secret;
+    secretAccessKey: Secret;
+}

package/lib/aws/oidc/oidc-provider.js

@@ -1,6 +1,6 @@
 import { CreateOpenIDConnectProviderCommand, DeleteOpenIDConnectProviderCommand, GetOpenIDConnectProviderCommand, GetRoleCommand, IAMClient, UpdateAssumeRolePolicyCommand, } from "@aws-sdk/client-iam";
 import { Resource } from "../../resource";
-import { getAccountId } from "../account-id";
+import { AccountId } from "../account-id";
 /**
  * AWS OIDC Provider Resource for GitHub Actions
  *
@@ -91,7 +91,7 @@ export const OIDCProvider = Resource("aws::OIDCProvider", async function (id, pr
         catch (error) {
             if (error.name === "EntityAlreadyExistsException") {
                 // Provider exists, use its ARN
-                providerArn = `arn:aws:iam::${await getAccountId()}:oidc-provider/${url}`;
+                providerArn = `arn:aws:iam::${await AccountId()}:oidc-provider/${url}`;
             }
             else {
                 throw error;

package/lib/aws/role.js

@@ -118,38 +118,50 @@ import { ignore } from "../util/ignore";
 export const Role = Resource("iam::Role", async function (id, props) {
     const client = new IAMClient({});
     if (this.phase === "delete") {
-        // Delete any inline policies first
-        if (props.policies) {
-            for (const policy of props.policies) {
-                await ignore(NoSuchEntityException.name, () => client.send(new DeleteRolePolicyCommand({
-                    RoleName: props.roleName,
-                    PolicyName: policy.policyName,
-                })));
-            }
-        }
-        // We need to detach managed policies before deleting the role
-        // First, get all attached policies
         try {
-            const attachedPoliciesResponse = await client.send(new ListAttachedRolePoliciesCommand({
-                RoleName: props.roleName,
-            }));
-            // Detach all managed policies
-            const attachedPolicies = attachedPoliciesResponse.AttachedPolicies || [];
-            for (const policy of attachedPolicies) {
-                await client.send(new DetachRolePolicyCommand({
+            // Delete any inline policies first
+            if (props.policies) {
+                for (const policy of props.policies) {
+                    await ignore(NoSuchEntityException.name, () => client.send(new DeleteRolePolicyCommand({
+                        RoleName: props.roleName,
+                        PolicyName: policy.policyName,
+                    })));
+                }
+            }
+            // We need to detach managed policies before deleting the role
+            // First, get all attached policies
+            try {
+                const attachedPoliciesResponse = await client.send(new ListAttachedRolePoliciesCommand({
                     RoleName: props.roleName,
-                    PolicyArn: policy.PolicyArn,
                 }));
+                // Detach all managed policies
+                const attachedPolicies = attachedPoliciesResponse.AttachedPolicies || [];
+                for (const policy of attachedPolicies) {
+                    await ignore(NoSuchEntityException.name, () => client.send(new DetachRolePolicyCommand({
+                        RoleName: props.roleName,
+                        PolicyArn: policy.PolicyArn,
+                    })));
+                }
             }
+            catch (error) {
+                if (error.name !== NoSuchEntityException.name) {
+                    throw error;
+                }
+                // Role doesn't exist, no need to continue with detaching policies
+            }
+            // Try to delete the role, ignoring if it doesn't exist
+            await ignore(NoSuchEntityException.name, () => client.send(new DeleteRoleCommand({
+                RoleName: props.roleName,
+            })));
         }
         catch (error) {
+            // If we get any other error besides NoSuchEntityException, log it but don't fail
+            // This ensures the resource is still marked as destroyed
             if (error.name !== NoSuchEntityException.name) {
-                throw error;
+                console.error(`Error deleting role ${props.roleName}:`, error);
             }
         }
-        await ignore(NoSuchEntityException.name, () => client.send(new DeleteRoleCommand({
-            RoleName: props.roleName,
-        })));
+        // Always return destroyed state regardless of any errors
         return this.destroy();
     }
     const assumeRolePolicyDocument = JSON.stringify(props.assumeRolePolicy);

package/lib/cloudflare/account-api-token.d.ts

@@ -0,0 +1,168 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { Secret } from "../secret";
+/**
+ * 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;
+}
+/**
+ * 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 declare const AccountApiToken: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<AccountApiToken>, id: string, props: AccountApiTokenProps) => Promise<AccountApiToken>);

package/lib/cloudflare/account-api-token.js

@@ -0,0 +1,179 @@
+import { alchemy } from "../alchemy";
+import { Resource } from "../resource";
+import { Secret } from "../secret";
+import { sha256 } from "../util/sha256";
+import { createCloudflareApi } from "./api";
+/**
+ * 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 (id, props) {
+    // 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 = 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) {
+        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 = 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 = 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/lib/cloudflare/account-id.d.ts

@@ -0,0 +1 @@
+export {};