@alchemy.run/archil 0.0.0 → 2.0.0-beta.86

package/src/ApiToken.ts

@@ -0,0 +1,168 @@
+import * as archil from "@distilled.cloud/archil";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { account } from "./Credentials.ts";
+import { isAlchemyName, tokenName } from "./internal/archil.ts";
+import type { Providers } from "./Providers.ts";
+
+export interface ApiTokenProps {
+  /**
+   * Token name, unique within your account. If omitted, a unique name is
+   * generated from the stack, stage, and logical ID. Changing it replaces
+   * the token.
+   */
+  name?: string;
+  /** Description shown in the console. Changing it replaces the token. */
+  description?: string;
+}
+
+export interface ApiTokenAttributes {
+  /** Token id. */
+  tokenId: string;
+  /** Token name. */
+  name: string;
+  /** Last characters of the key, as shown in the console. */
+  tokenSuffix: string | undefined;
+  /** The API key (`key-…`). */
+  token: Redacted.Redacted<string>;
+  /** Archil region the key was created for, e.g. `aws-us-east-1`. */
+  region: string;
+}
+
+export type ApiToken = Resource<
+  "Archil.ApiToken",
+  ApiTokenProps,
+  ApiTokenAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * An Archil API key. It can call the whole control plane of your account:
+ * Archil has no scoped keys, so give each app or host its own key and
+ * revoke it on its own. To mount one disk, use a {@link DiskUser}, whose
+ * token works only for that disk.
+ *
+ * Archil only shows the key once, when it's created, so Alchemy stores it
+ * in state as a `Redacted` value. Changing a prop creates a new key, and
+ * destroying it revokes the key.
+ *
+ * Archil refuses API keys on its API key operations: deploying with one
+ * fails with `Unauthorized`, the same error a bad key gets.
+ * @see https://docs.archil.com/api-reference
+ *
+ * ### Creating a Key
+ * **Example:** A key for CI
+ * ```typescript
+ * const key = yield* Archil.ApiToken("Ci", { description: "GitHub Actions" });
+ * ```
+ *
+ * @resource
+ * @product API Key
+ */
+export const ApiToken = Resource<ApiToken>("Archil.ApiToken");
+
+const observe = Effect.fn(function* (match: { tokenId?: string; name: string }) {
+  const { data } = yield* archil.listApiTokens({});
+  return (data.tokens ?? []).find((token) =>
+    match.tokenId !== undefined ? token.id === match.tokenId : token.name === match.name,
+  );
+});
+
+const revoke = (tokenId: string) =>
+  archil.deleteToken({ id: tokenId }).pipe(
+    Effect.asVoid,
+    Effect.catchTag("NotFound", () => Effect.void),
+  );
+
+/** Create an API key and return its attributes. */
+export const createApiToken = Effect.fn(function* (name: string, description?: string) {
+  const { data } = yield* archil.createApiToken({ name, description });
+  const { region } = yield* account;
+  return {
+    tokenId: data.id,
+    name,
+    tokenSuffix: data.tokenSuffix,
+    token: typeof data.token === "string" ? Redacted.make(data.token) : data.token,
+    region,
+  } satisfies ApiTokenAttributes;
+});
+
+export const ApiTokenProvider = () =>
+  Provider.effect(
+    ApiToken,
+    Effect.gen(function* () {
+      return {
+        stables: ["tokenId", "name", "tokenSuffix", "token", "region"],
+        list: Effect.fn(function* () {
+          const { region } = yield* account;
+          const { data } = yield* archil.listApiTokens({});
+          return (data.tokens ?? [])
+            .filter((token) => isAlchemyName(token.name))
+            .map((token) => ({
+              tokenId: token.id ?? "",
+              name: token.name ?? "",
+              tokenSuffix: token.tokenSuffix,
+              token: Redacted.make(""),
+              region,
+            }));
+        }),
+        diff: Effect.fn(function* ({ id, olds, news, output }) {
+          if (!isResolved(news)) return undefined;
+          const name = output?.name ?? (yield* tokenName(id, olds?.name));
+          if (
+            (news.name !== undefined && news.name !== name) ||
+            news.description !== olds?.description
+          ) {
+            return {
+              action: "replace",
+              deleteFirst: news.name !== undefined && news.name === name,
+            } as const;
+          }
+          return undefined;
+        }),
+        read: Effect.fn(function* ({ id, olds, output, previous }) {
+          const name = output?.name ?? (yield* tokenName(id, olds?.name));
+          const observed = yield* observe({ tokenId: output?.tokenId, name });
+          if (!observed) return undefined;
+          if (output !== undefined && output.tokenId === observed.id) return output;
+          if (previous !== undefined && previous.tokenId === observed.id) return previous;
+          // The key is only revealed at creation, so a token we have no state
+          // for can't be adopted with its value — reconcile re-mints.
+          return Unowned({
+            tokenId: observed.id ?? "",
+            name,
+            tokenSuffix: observed.tokenSuffix,
+            token: Redacted.make(""),
+            region: (yield* account).region,
+          });
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const name = output?.name ?? (yield* tokenName(id, news.name));
+          // Observe
+          const observed = yield* observe({ tokenId: output?.tokenId, name });
+          if (
+            observed &&
+            output &&
+            Redacted.value(output.token) !== "" &&
+            output.tokenId === observed.id
+          ) {
+            return output;
+          }
+          // Ensure — a key we hold no secret for is revoked and re-minted.
+          if (observed?.id) {
+            yield* session.note(`Re-minting API token ${name}...`);
+            yield* revoke(observed.id);
+          }
+          return yield* createApiToken(name, news.description);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* revoke(output.tokenId);
+        }),
+      };
+    }),
+  );

package/src/ArchilBindings.ts

@@ -0,0 +1,179 @@
+/**
+ * How Archil bindings reach Archil from any host.
+ *
+ * Archil only mints API keys from a console session and can't scope them,
+ * so a host's control-plane clients use the key the stack deploys with,
+ * recorded per host and read back at run time. Hosts that only touch one
+ * disk never hold an API key: the object bindings get a per-host S3
+ * `Archil.DiskUser` (read-only for `ReadDisk`), and `MountDisk` a per-host
+ * token user.
+ */
+import { controlPlaneUrl, Credentials, DEFAULT_REGION } from "@distilled.cloud/archil/Credentials";
+import * as Objects from "@distilled.cloud/archil/Objects";
+import { ConfigError } from "@distilled.cloud/core/errors";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import { Stack } from "alchemy/Stack";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import type * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import type { Disk } from "./Disk.ts";
+import { DiskUser } from "./DiskUser.ts";
+import { DeployerKey } from "./internal/DeployerKey.ts";
+
+/** Runs disk object effects and streams with one set of object credentials. */
+export interface ObjectsRunner {
+  <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ): Effect.Effect<
+    A,
+    E,
+    Exclude<R, Objects.ObjectCredentials | HttpClient.HttpClient> | RuntimeContext
+  >;
+  stream<A, E, R>(
+    stream: Stream.Stream<A, E, R>,
+  ): Stream.Stream<
+    A,
+    E,
+    Exclude<R, Objects.ObjectCredentials | HttpClient.HttpClient> | RuntimeContext
+  >;
+}
+
+/** Runs Archil SDK effects and streams with the host's own API key. */
+export interface Authorize {
+  <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, E, Exclude<R, Credentials | HttpClient.HttpClient> | RuntimeContext>;
+  stream<A, E, R>(
+    stream: Stream.Stream<A, E, R>,
+  ): Stream.Stream<A, E, Exclude<R, Credentials | HttpClient.HttpClient> | RuntimeContext>;
+  /** Disk object calls with the same API key. */
+  readonly objects: ObjectsRunner;
+}
+
+// TypeScript can't infer a generic call signature whose requirement is
+// `Exclude<R, …>` from `Effect.provide`, so runners assert their shape.
+const runnerOf = <Rm>(layer: Layer.Layer<Rm>) => ({
+  run: <A, E, R>(effect: Effect.Effect<A, E, R>) => effect.pipe(Effect.provide(layer)),
+  stream: <A, E, R>(stream: Stream.Stream<A, E, R>) => stream.pipe(Stream.provide(layer)),
+});
+
+/**
+ * Record (at deploy) and read back (at run time) the API key a host's
+ * Archil clients call the control plane with. Every Archil binding on one
+ * host shares one record (the engine de-duplicates the declaration).
+ */
+export const ApiAccess = Effect.gen(function* () {
+  const Key = yield* DeployerKey;
+  return Effect.fn(function* () {
+    const host = yield* Binding.Host;
+    const token = yield* Key(`${host?.LogicalId ?? "Script"}ArchilApiKey`, {});
+    const apiKey = yield* token.apiKey;
+    const region = yield* token.region;
+    const credentials = Effect.all([apiKey, region]).pipe(
+      Effect.map(([key, r]) => ({
+        apiKey: key,
+        apiBaseUrl: controlPlaneUrl(r) ?? controlPlaneUrl(DEFAULT_REGION)!,
+        region: r,
+      })),
+    );
+    const layer = Layer.mergeAll(Objects.ObjectCredentialsFromApiKey, FetchHttpClient.layer).pipe(
+      Layer.provideMerge(Layer.succeed(Credentials, credentials)),
+    );
+    const { run, stream } = runnerOf(layer);
+    const objects = Object.assign(run, { stream }) as unknown as ObjectsRunner;
+    return Object.assign(run, { stream, objects }) as unknown as Authorize;
+  });
+});
+
+/**
+ * Create (at deploy) and read back (at run time) a per-host S3 user on one
+ * disk, and run object calls signed with its keys. The keys reach only
+ * that disk, and only `GET`/`HEAD` when `readOnly`. Every object binding
+ * of one kind on one host shares one user (the engine de-duplicates the
+ * declaration).
+ */
+export const DiskKeyAccess = Effect.gen(function* () {
+  const Users = yield* DiskUser;
+  return Effect.fn(function* (disk: Disk, access: "read" | "write") {
+    const host = yield* Binding.Host;
+    const user = yield* Users(
+      `${host?.LogicalId ?? "Script"}${disk.LogicalId}${access === "read" ? "Reader" : "Writer"}`,
+      { disk: disk.diskId, type: "s3", readOnly: access === "read" },
+    );
+    const accessKeyId = yield* user.accessKeyId;
+    const secretAccessKey = yield* user.secretAccessKey;
+    const region = yield* disk.region;
+    const auth = Effect.gen(function* () {
+      const keyId = yield* accessKeyId;
+      const secret = yield* secretAccessKey;
+      if (keyId === undefined || secret === undefined) {
+        return yield* new ConfigError({
+          message: `The S3 user for ${disk.LogicalId} has no keys; redeploy to create them again.`,
+        });
+      }
+      return yield* Objects.diskKeysAuth({
+        region: yield* region,
+        accessKeyId: keyId,
+        secretAccessKey: secret,
+      });
+    });
+    const layer = Layer.mergeAll(
+      Layer.succeed(Objects.ObjectCredentials, auth),
+      FetchHttpClient.layer,
+    );
+    const { run, stream } = runnerOf(layer);
+    return Object.assign(run, { stream }) as unknown as ObjectsRunner;
+  });
+});
+
+/** What every name a run-time client creates starts with. */
+export const RUNTIME_NAME_MARKER = "alc-";
+
+const toNameLabel = (value: string) =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+
+/** FNV-1a, 32-bit, as 8 hex digits: the same on every host, no crypto API needed. */
+const fnv1a = (value: string) => {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+};
+
+/**
+ * The owner a binding's run-time client stamps on what it creates. Archil
+ * disks and sandboxes have no tags, labels or descriptions, only a name,
+ * so the owner (`alchemy::stack`, `alchemy::stage`, `alchemy::id`) is a
+ * name prefix: `alc-<id>-<hash of stack/stage/id>`. Hosts know their stack
+ * and stage at run time (`ALCHEMY_STACK_NAME`, `ALCHEMY_STAGE`), so the
+ * prefix is the same at deploy and at run time without a resource.
+ * Destroying the stack doesn't delete what carries it.
+ */
+export const runtimePrefix = Effect.fn(function* (label: string) {
+  const host = yield* Binding.Host;
+  const stack = yield* Effect.serviceOption(Stack);
+  const tags = {
+    "alchemy::stack": Option.isSome(stack) ? stack.value.name : "",
+    "alchemy::stage": Option.isSome(stack) ? stack.value.stage : "",
+    "alchemy::id": `${host?.LogicalId ?? "Script"}${label}`,
+  };
+  const owner = `${tags["alchemy::stack"]}/${tags["alchemy::stage"]}/${tags["alchemy::id"]}`;
+  const readable = toNameLabel(tags["alchemy::id"]).slice(0, 14).replace(/-+$/, "") || "x";
+  return {
+    prefix: `${RUNTIME_NAME_MARKER}${readable}-${fnv1a(owner)}`,
+    tags,
+  };
+});
+
+/** `<prefix>-<name>`. */
+export const runtimeName = (prefix: string, name: string) => `${prefix}-${name}`;

package/src/AuthProvider.ts

@@ -0,0 +1,122 @@
+import { DEFAULT_REGION, REGIONS } from "@distilled.cloud/archil/Credentials";
+import { AuthError } from "alchemy/Auth/AuthProvider";
+import { getEnv, getEnvRedacted } from "alchemy/Auth/Env";
+import {
+  makeStoredAuthProvider,
+  storedSecret,
+  storedValueText,
+  type StoredAuthConfig,
+} from "alchemy/Auth/StoredAuthProvider";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+
+/**
+ * Canonical name registered in the AuthProviders registry. Use this key to
+ * look up the Archil AuthProvider from inside provider Layers.
+ */
+export const ARCHIL_AUTH_PROVIDER_NAME = "Archil";
+
+export type ArchilAuthConfig = StoredAuthConfig;
+
+/**
+ * Resolved Archil credentials.
+ *
+ * Archil's control plane authenticates with account API keys (created in
+ * the console). Every disk, sandbox and image
+ * lives in one region, which picks the control plane and S3 endpoints.
+ */
+export interface ArchilResolvedCredentials {
+  type: "apiKey";
+  apiKey: Redacted.Redacted<string>;
+  /** Archil region id, e.g. `aws-us-east-1`. */
+  region: string;
+  /**
+   * Archil organization id. Only needed to scope bucket policies on
+   * bring-your-own-bucket disks to your organization.
+   */
+  organization: string | undefined;
+  source: { type: ArchilAuthConfig["method"] | "env"; details?: string };
+}
+
+const validateRegion = (value: string) =>
+  value in REGIONS ? undefined : `One of ${Object.keys(REGIONS).join(", ")}`;
+
+const readEnvironment = Effect.gen(function* () {
+  const apiKey = yield* getEnvRedacted("ARCHIL_API_KEY");
+  if (apiKey === undefined || Redacted.value(apiKey).trim().length === 0) {
+    return yield* AuthError.make({
+      message: "Archil CI credentials not found. Set ARCHIL_API_KEY.",
+    });
+  }
+  return {
+    type: "apiKey" as const,
+    apiKey: Redacted.make(Redacted.value(apiKey).trim()),
+    region: (yield* getEnv("ARCHIL_REGION")) ?? DEFAULT_REGION,
+    organization: yield* getEnv("ARCHIL_ORGANIZATION"),
+    source: { type: "env" as const, details: "ARCHIL_API_KEY" },
+  } satisfies ArchilResolvedCredentials;
+});
+
+const archilAuth = makeStoredAuthProvider<ArchilResolvedCredentials>({
+  provider: ARCHIL_AUTH_PROVIDER_NAME,
+  fields: [
+    {
+      name: "apiKey",
+      label: "Archil API Key",
+      description: "Create one at https://console.archil.com (API Keys). It starts with `key-`.",
+      secret: true,
+      validate: (value) => (value.trim().length === 0 ? "Required" : undefined),
+    },
+    {
+      name: "region",
+      label: "Archil Region",
+      description: `Region your disks and sandboxes live in. Defaults to ${DEFAULT_REGION}.`,
+      optional: true,
+      validate: (value) => (value.trim().length === 0 ? undefined : validateRegion(value.trim())),
+    },
+    {
+      name: "organization",
+      label: "Archil Organization ID",
+      description:
+        "Only needed for disks on your own S3 bucket: scopes the bucket policy to your organization.",
+      optional: true,
+    },
+  ],
+  toResolved: (values, source) => ({
+    type: "apiKey",
+    apiKey: storedSecret(values.apiKey) ?? Redacted.make(""),
+    region: storedValueText(values.region) || DEFAULT_REGION,
+    organization: storedValueText(values.organization) || undefined,
+    source: { type: source },
+  }),
+  readEnvironment,
+  environment: [
+    {
+      name: "ARCHIL_API_KEY",
+      required: true,
+      secret: true,
+      description: "Archil API key.",
+    },
+    {
+      name: "ARCHIL_REGION",
+      required: false,
+      description: `Archil region id. Defaults to ${DEFAULT_REGION}.`,
+    },
+    {
+      name: "ARCHIL_ORGANIZATION",
+      required: false,
+      description: "Archil organization id, for bring-your-own-bucket disk policies.",
+    },
+  ],
+});
+
+/**
+ * Layer that registers the Archil AuthProvider into the AuthProviders
+ * registry when built. Included in `Archil.providers()` so the alchemy CLI
+ * (`alchemy profile edit`) can configure it.
+ */
+export const ArchilAuth = archilAuth.layer;
+
+/** Schema of Archil's inline API-key values. */
+export const ArchilStoredCredentials = archilAuth.storedSchema;
+export type ArchilStoredCredentials = typeof ArchilStoredCredentials.Type;

package/src/Bootstrap.ts

@@ -0,0 +1,54 @@
+/**
+ * Process bootstrap for an `Archil.Sandbox` program (a Node process serving the
+ * bundled program). The generated entry imports this module and the user's
+ * `main`, nothing else — see `alchemy/Runtime/Bootstrap` for why.
+ */
+import { NodeServices } from "@effect/platform-node";
+import { NodeHttpServer } from "alchemy/Http";
+import { reifyBoundConfigProvider } from "alchemy/Runtime";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "alchemy/Runtime/Bootstrap";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as SecureRandom from "effect/crypto/SecureRandom";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+
+/**
+ * Resolve the bundled program (the runners registered via `host.run` /
+ * serve) and run it with a Node HTTP server bound to `PORT`, so the
+ * returned `{ fetch }` handler is actually served and `host.run` loops
+ * stay alive.
+ */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    NodeServices.layer,
+    FetchHttpClient.layer,
+    SecureRandom.layerWebCrypto,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program").pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        Layer.provideMerge(NodeHttpServer({ hostname: "0.0.0.0" })),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Archil service", program);
+};