sailfork / t3code-github / .repos/ alchemy-effect/ packages/ fly/ src/ Secret.ts

import { createHash } from "node:crypto";
import type { AppSecret } from "@distilled.cloud/fly-io/machines";
import * as machines from "@distilled.cloud/fly-io/machines";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import { App, listOwnedApps } from "./App.ts";
import { createFlyVolumeName, matchesAlchemyPhysicalName } from "./Metadata.ts";
import type { Providers } from "./Providers.ts";

/**
 * A resource-valued prop: the resource itself, or an Effect that produces
 * it (so `yield* App(...)` and `App(...)` both type-check).
 */
type Ref<T> = T | Effect.Effect<T, never, Providers>;

export interface SecretProps {
  /**
   * Parent Fly App. Changing it replaces the secret.
   */
  app: Ref<App>;
  /**
   * Secret name. Used as the Machine env-var name when set by the user
   * (case-sensitive, stored as-is). If omitted, a unique name is generated
   * from the stack, stage and logical ID (the ownership stamp). Changing
   * it replaces the secret.
   */
  name?: string;
  /**
   * Secret value. Wrap with `Redacted.make(...)` so it is never logged.
   * Updated in place via `updateSecrets`. Never persisted in attributes.
   */
  value: Redacted.Redacted<string> | string;
}

export type Secret = Resource<
  "Fly.Secret",
  SecretProps,
  {
    /** Parent Fly App name. */
    appName: string;
    /** Secret name (unique per App). */
    name: string;
    /** Fly digest of the current value. Not the plaintext. */
    digest: string | undefined;
    /** RFC3339 creation timestamp. */
    createdAt: string | undefined;
    /** RFC3339 last-update timestamp. */
    updatedAt: string | undefined;
  },
  never,
  Providers
>;

const resolveSecretProps = (
  props: SecretProps | Effect.Effect<SecretProps, never, Providers>,
): Effect.Effect<SecretProps, never, Providers> =>
  Effect.gen(function* () {
    const resolved = Effect.isEffect(props) ? yield* props : props;
    if (globalThis.__ALCHEMY_RUNTIME__) return resolved;
    const app = Effect.isEffect(resolved.app)
      ? yield* resolved.app as Effect.Effect<App, never, Providers>
      : resolved.app;
    return { ...resolved, app };
  });

const SecretResource = Resource<Secret>("Fly.Secret");

/**
 * A Fly.Secret is an App vault entry. Fly injects it as an environment
 * variable on every Machine. Use it when the value is shared and
 * managed in one place by Fly.
 *
 * For a secret only this {@link Service} reads from `.env` at deploy
 * time, yield `Config.Redacted` instead. Do not pass `env: { ... }` on
 * a Service.
 *
 * @see https://fly.io/docs/apps/secrets/
 *
 * ### Config.Redacted on a Service
 * Most secrets in a Service come from your `.env`. Yield
 * `Config.Redacted` in init. Alchemy binds the value onto the Machine.
 *
 * **Example:** Bind from .env
 * ```typescript
 * import * as Config from "effect/Config";
 * import * as Redacted from "effect/Redacted";
 *
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { app: Site, main: import.meta.url, port: 3000 },
 *   Effect.gen(function* () {
 *     const apiKey = yield* Config.Redacted("API_KEY");
 *
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const token = Redacted.value(apiKey);
 *         return HttpServerResponse.text("ok");
 *       }),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Create a Secret
 * Wrap the value with `Redacted.make` so it is never logged. The
 * plaintext is never stored in attributes. Omit `name` and Alchemy
 * generates an ownership-stamped name.
 *
 * **Example:** Generated name
 * ```typescript
 * const dbUrl = yield* Fly.Secret("DatabaseUrl", {
 *   app: Site,
 *   value: Redacted.make("postgres://…"),
 * });
 * ```
 *
 * :::caution[Changing `app` replaces the Secret]
 * The value is created on the new App. The old name is deleted.
 * :::
 *
 * ### Env-var name
 * `name` is the env-var Machines see. It is stored as-is
 * (case-sensitive).
 *
 * **Example:** Explicit name
 * ```typescript
 * export const ApiToken = Fly.Secret("ApiToken", {
 *   app: Site,
 *   name: "API_TOKEN",
 *   value: Redacted.make("sk_live_…"),
 * });
 * ```
 *
 * :::caution[Changing `name` replaces the Secret]
 * Fly cannot rename a secret. Alchemy creates the new name, then
 * deletes the old one.
 * :::
 *
 * ### Rotate the value
 * Updating `value` is in place via `updateSecrets`.
 *
 * **Example:** New value
 * ```typescript
 * export const ApiToken = Fly.Secret("ApiToken", {
 *   app: Site,
 *   name: "API_TOKEN",
 *   value: Redacted.make("sk_live_rotated"),
 * });
 * ```
 *
 * ### Get a secret at runtime
 * {@link GetSecret} is bound to one Secret. Provide
 * {@link GetSecretHttp}. Fly only returns plaintext from a Machine in
 * the same App. From a deploy-time Action you get metadata (name,
 * digest, timestamps).
 *
 * **Example:** GetSecret
 * ```typescript
 * const get = yield* Fly.GetSecret(ApiToken);
 * const got = yield* get();
 * ```
 *
 * ### List secrets
 * {@link ListSecrets} is bound to an {@link App}. From an Action, the
 * org token can list any App in the org. From a Machine, deploy tokens
 * are per-App. Mixing Apps on one Machine shares one `FLY_API_TOKEN`
 * and is not supported.
 *
 * **Example:** ListSecrets
 * ```typescript
 * const list = yield* Fly.ListSecrets(Site);
 * const { secrets } = yield* list();
 * ```
 *
 * ### Write secrets
 * {@link WriteSecret} creates, updates, and deletes by name. Provide
 * {@link WriteSecretHttp} on the Action or Service Effect.
 *
 * **Example:** Rotate from an Action
 * ```typescript
 * const Seed = Alchemy.Action(
 *   "Seed",
 *   Effect.gen(function* () {
 *     const secrets = yield* Fly.WriteSecret(ApiToken);
 *
 *     return Effect.fn(function* () {
 *       yield* secrets.update("API_TOKEN", Redacted.make("sk_live_rotated"));
 *     });
 *   }).pipe(Effect.provide(Fly.WriteSecretHttp)),
 * );
 * ```
 *
 * @resource
 * @product Secret
 */
export const Secret: typeof SecretResource = Object.assign(
  (id: string, props: SecretProps | Effect.Effect<SecretProps, never, Providers>) =>
    SecretResource(id, resolveSecretProps(props)),
  SecretResource,
);

export class SecretNotCreated extends Data.TaggedError("Fly.SecretNotCreated")<{
  appName: string;
  secretName: string;
}> {}

export class SecretAppRequired extends Data.TaggedError("Fly.SecretAppRequired")<{
  message: string;
}> {}

const appNameOf = (value: unknown): string | undefined => {
  if (value === null || typeof value !== "object") return undefined;
  const rec = value as { appName?: unknown };
  return typeof rec.appName === "string" && rec.appName.length > 0 ? rec.appName : undefined;
};

const unwrapSecret = (value: Redacted.Redacted<string> | string): string =>
  Redacted.isRedacted(value) ? Redacted.value(value) : value;

const resolveName = (id: string, name: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    // User env-var names are stored as-is (case-sensitive). Generated
    // names use the Volume underscore shape — Fly rejects hyphens.
    if (name !== undefined) return name;
    if (existing !== undefined) return existing;
    return yield* createFlyVolumeName(id);
  });

const toAttrs = (
  appName: string,
  secret: AppSecret,
  fallbackName: string,
): Secret["Attributes"] => ({
  appName,
  name: secret.name ?? fallbackName,
  digest: secret.digest,
  createdAt: secret.created_at,
  updatedAt: secret.updated_at,
});

const getByName = (appName: string, secretName: string) =>
  machines
    .getSecret({
      app_name: appName,
      secret_name: secretName,
      show_secrets: false,
    })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const listSecrets = (appName: string) =>
  machines
    .listSecrets({
      app_name: appName,
      show_secrets: false,
    })
    .pipe(
      Effect.map((res) => res.secrets ?? []),
      Effect.catchTag(["NotFound", "Forbidden"], () => Effect.succeed([])),
    );

const flyDigestCandidates = (plain: string) =>
  Effect.sync(() => {
    const utf8 = Buffer.from(plain, "utf8");
    return [
      createHash("md5").update(utf8).digest("hex"),
      createHash("sha256").update(utf8).digest("hex"),
    ];
  });

export const SecretProvider = () =>
  Provider.succeed(Secret, {
    stables: ["appName", "name", "createdAt"],
    nuke: { dependsOn: ["Fly.App"] },

    diff: Effect.fn(function* ({ news, output }) {
      if (news === undefined || !isResolved(news)) return undefined;
      if (output === undefined) return undefined;
      const desiredName = news.name !== undefined ? news.name : output.name;
      const nameChanged = desiredName !== output.name;
      const nextApp = appNameOf(news.app);
      const appChanged = nextApp !== undefined && nextApp !== output.appName;
      if (nameChanged || appChanged) {
        return {
          action: "replace" as const,
          // Same (app, name) cannot exist twice — delete the old secret first.
          deleteFirst: nameChanged && !appChanged,
        };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const appName = output?.appName ?? (olds !== undefined ? appNameOf(olds.app) : undefined);
      if (appName === undefined) return undefined;
      const name = yield* resolveName(id, olds?.name, output?.name);
      const found = yield* getByName(appName, name);
      if (found === undefined) return undefined;
      const attrs = toAttrs(appName, found, name);
      if (output !== undefined) return attrs;
      return matchesAlchemyPhysicalName(name) ? attrs : Unowned(attrs);
    }),

    list: Effect.fn(function* () {
      const apps = yield* listOwnedApps();
      const rows = yield* Effect.forEach(
        apps,
        (app) =>
          listSecrets(app.appName).pipe(
            Effect.map((secrets) =>
              secrets.flatMap((secret) => {
                const name = secret.name;
                if (!matchesAlchemyPhysicalName(name)) return [];
                return [toAttrs(app.appName, secret, name ?? "")];
              }),
            ),
          ),
        { concurrency: 8 },
      );
      return rows.flat();
    }),

    reconcile: Effect.fn(function* ({ id, news, olds, output }) {
      const props = news ?? ({} as SecretProps);
      const appName = appNameOf(props.app) ?? output?.appName;
      if (appName === undefined) {
        return yield* new SecretAppRequired({
          message: "Secret requires a resolved Fly.App",
        });
      }
      const name = yield* resolveName(id, props.name, output?.name);
      const desiredPlain = unwrapSecret(props.value);

      // Observe by cached identity, then the desired (app, name).
      let current =
        output !== undefined ? yield* getByName(output.appName, output.name) : undefined;
      if (
        current === undefined &&
        (output === undefined || output.appName !== appName || output.name !== name)
      ) {
        current = yield* getByName(appName, name);
      }

      let createdThisRun = false;
      if (current === undefined) {
        yield* machines
          .createSecret({
            app_name: appName,
            secret_name: name,
            value: desiredPlain,
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.void));
        current = yield* getByName(appName, name);
        createdThisRun = true;
      }

      if (current === undefined) {
        return yield* new SecretNotCreated({ appName, secretName: name });
      }

      // Sync — skip if we just created. Prefer observed digest vs hash of
      // desired; otherwise re-put when olds is absent (adoption) or the
      // previous value differs. Never log the plaintext.
      if (!createdThisRun) {
        const candidates = yield* flyDigestCandidates(desiredPlain);
        const digestMatches = current.digest !== undefined && candidates.includes(current.digest);
        const previousPlain = olds?.value !== undefined ? unwrapSecret(olds.value) : undefined;
        const valueChanged = previousPlain === undefined || previousPlain !== desiredPlain;
        if (!digestMatches && valueChanged) {
          yield* machines
            .updateSecrets({
              app_name: appName,
              values: { [name]: desiredPlain },
            })
            .pipe(Effect.catchTag("Conflict", () => Effect.void));
          current = (yield* getByName(appName, name)) ?? current;
        }
      }

      return toAttrs(appName, current, name);
    }),

    delete: Effect.fn(function* ({ output }) {
      if (output.appName.length === 0 || output.name.length === 0) return;
      yield* machines
        .deleteSecret({
          app_name: output.appName,
          secret_name: output.name,
        })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
      yield* getByName(output.appName, output.name).pipe(
        Effect.map((secret) => secret === undefined),
        Effect.repeat({
          schedule: Schedule.spaced("1 second"),
          until: (gone) => gone,
          times: 8,
        }),
      );
    }),
  });