@alchemy.run/fly 2.0.0-beta.85 → 2.0.0-beta.86

package/src/BindService.ts

@@ -1,6 +1,6 @@
 import * as Binding from "alchemy/Binding";
 import type { Resource } from "alchemy/Resource";
-import { makeFetchRpcStub, RPC_PATH_PREFIX, type Rpc } from "alchemy/Rpc";
+import { makeFetchRpcStub, type Rpc } from "alchemy/Rpc";
 import { CurrentRuntimeContext, type RuntimeContext, sanitizeKey } from "alchemy/RuntimeContext";
 import { isYieldableEffectLike } from "alchemy/Util/effect";
 import * as Data from "effect/Data";
@@ -9,9 +9,7 @@ import * as HttpClient from "effect/http/HttpClient";
 import type * as HttpClientError from "effect/http/HttpClientError";
 import * as HttpClientRequest from "effect/http/HttpClientRequest";
 import type * as HttpClientResponse from "effect/http/HttpClientResponse";
-import * as Redacted from "effect/Redacted";
 import type { BoundTarget, ServiceBinding } from "./MountVolume.ts";
-import { RPC_TOKEN_HEADER } from "./rpc.ts";
 import type { Service } from "./Service.ts";
 
 /** The deployed caller has no address for the bound Service. */
@@ -75,12 +73,13 @@ const logicalIdOf = (target: unknown): string => {
 export const boundTargetEnvKeys = (id: string) => ({
   appName: sanitizeKey(`FLY_BIND_${id}_APP`),
   url: sanitizeKey(`FLY_BIND_${id}_URL`),
-  token: sanitizeKey(`FLY_BIND_${id}_TOKEN`),
 });
 
 /**
  * Record the binding on the caller and transport the target's private
- * address and caller token as Outputs. Returns runtime accessors for them.
+ * address as Outputs. For {@link bindService}, also record the caller's
+ * App on the target, which serves its methods only to the Apps recorded
+ * there. Returns runtime accessors for the address.
  */
 const bindTarget = Effect.fn(function* <Shape, Req>(
   target: Target<Shape> | Effect.Effect<Target<Shape>, never, Req>,
@@ -105,11 +104,22 @@ const bindTarget = Effect.fn(function* <Shape, Req>(
           appName: service.appName,
           network: service.network,
           privateUrl: service.privateUrl,
-          rpcToken: service.rpcToken,
           port,
           endpoints: service.endpoints,
         } as unknown as BoundTarget,
       });
+      if (port === undefined) {
+        // Fly signs each request's calling App (`Fly-Src`), so the target
+        // authorizes callers by App: no key to hand out.
+        yield* (
+          service as unknown as {
+            bind: (
+              label: TemplateStringsArray,
+              ...args: unknown[]
+            ) => (data: ServiceBinding) => Effect.Effect<void>;
+          }
+        ).bind`Caller(${host})`({ caller: { appName: host.appName as unknown as string } });
+      }
     }
   }
   // Captured at bind time: the host's runtime context reads the values
@@ -126,15 +136,6 @@ const bindTarget = Effect.fn(function* <Shape, Req>(
   return {
     appName: required(keys.appName),
     url: required(keys.url),
-    token: read(keys.token).pipe(
-      Effect.map((value) =>
-        Redacted.isRedacted(value)
-          ? String(Redacted.value(value))
-          : typeof value === "string"
-            ? value
-            : "",
-      ),
-    ),
   };
 });
 
@@ -150,12 +151,13 @@ const withBase = (base: string, url: string) => {
  * `fetch` and `run`) and forwards `fetch` requests, over Fly's private
  * network.
  *
- * Binding makes the caller deploy after the Service and hands it the
- * Service's private address and caller token. Only callers that bind a
- * Service receive its token, so other Services on the same network cannot
- * call its methods. Every call must also carry Fly's signed `Fly-Src`
- * header from the same organization, so the public internet cannot call
- * them. Calls are plain HTTP inside Fly's WireGuard-encrypted network.
+ * Binding makes the caller deploy after the Service, hands it the
+ * Service's private address, and records the caller's App on the Service.
+ * Fly's proxy signs every call with the calling App (`Fly-Src`), and the
+ * Service answers methods only for the Apps recorded on it, so neither
+ * other Services on the network nor the public internet can call them,
+ * and no key is involved. Calls are plain HTTP inside Fly's
+ * WireGuard-encrypted network.
  *
  * ### Call a private Service
  * **Example:** Methods on the target
@@ -250,24 +252,15 @@ export const bindService = <Shape, Req = never>(
   Effect.gen(function* () {
     const http = yield* HttpClient.HttpClient;
     const bound = yield* bindTarget(target, undefined);
-    const send = (request: HttpClientRequest.HttpClientRequest, isRpc: boolean) =>
+    const send = (request: HttpClientRequest.HttpClientRequest) =>
       Effect.gen(function* () {
         const base = yield* bound.url;
-        let next = HttpClientRequest.setUrl(request, withBase(base, request.url));
-        if (isRpc) {
-          next = HttpClientRequest.setHeader(next, RPC_TOKEN_HEADER, yield* bound.token);
-        }
-        return yield* http.execute(next);
+        return yield* http.execute(HttpClientRequest.setUrl(request, withBase(base, request.url)));
       });
     return makeFetchRpcStub<ServiceClient<Shape>>({
       fetch: (request) =>
-        send(request, request.url.includes(RPC_PATH_PREFIX)) as Effect.Effect<
-          HttpClientResponse.HttpClientResponse,
-          unknown
-        >,
-      base: {
-        fetch: (request: HttpClientRequest.HttpClientRequest) => send(request, false),
-      },
+        send(request) as Effect.Effect<HttpClientResponse.HttpClientResponse, unknown>,
+      base: { fetch: send },
     });
   });
 

package/src/Bootstrap.ts

@@ -14,6 +14,7 @@ import {
 } from "alchemy/Runtime/Bootstrap";
 import { ManagedHttpShutdown } from "alchemy/Runtime/ManagedHttpShutdown";
 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";
@@ -31,6 +32,7 @@ export const bootstrap = (entrypoint: unknown): Promise<void> => {
   const platform = Layer.mergeAll(
     NodeServices.layer,
     FetchHttpClient.layer,
+    SecureRandom.layerWebCrypto,
     Logger.layer([Logger.consolePretty()]),
   );
 

package/src/Bucket.ts

@@ -1,3 +1,7 @@
+import { fromCredentials, type Credentials } from "@distilled.cloud/aws/Credentials";
+import * as AwsEndpoint from "@distilled.cloud/aws/Endpoint";
+import type { RegionName } from "@distilled.cloud/aws/Region";
+import * as S3 from "@distilled.cloud/aws/s3";
 import type { AddOnsResponseEdgesItemNode } from "@distilled.cloud/fly-io/addons";
 import * as addons from "@distilled.cloud/fly-io/addons";
 import * as machines from "@distilled.cloud/fly-io/machines";
@@ -9,6 +13,9 @@ import { createInternalTags } from "alchemy/Tags";
 import * as Data from "effect/Data";
 import * as Duration from "effect/Duration";
 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 Redacted from "effect/Redacted";
 import * as Result from "effect/Result";
 import * as Schedule from "effect/Schedule";
@@ -133,9 +140,19 @@ export type Bucket = Resource<
     bucketName: Redacted.Redacted<string> | undefined;
   },
   never,
-  Providers
+  Providers,
+  BucketLookup
 >;
 
+/**
+ * Props for {@link Bucket.lookup}: find a Tigris bucket this stack
+ * doesn't manage by its name.
+ */
+export interface BucketLookup {
+  /** Tigris bucket / add-on name. */
+  name: string;
+}
+
 /**
  * A Fly.Bucket is Tigris S3-compatible object storage, billed through
  * Fly. It is an org-scoped GraphQL add-on (`AddOnType` `tigris`).
@@ -245,6 +262,18 @@ export type Bucket = Resource<
  * });
  * ```
  *
+ * ### Looking up an existing bucket
+ * `Bucket.lookup` references a bucket Alchemy doesn't manage (created with
+ * `fly storage create` or by another stack). It is read during plan/deploy,
+ * never created, updated or deleted. Tigris returns a bucket's access keys
+ * only when it is created, so a looked-up bucket's credential attributes
+ * are `undefined` unless Fly still reports them.
+ *
+ * **Example:** Reference an existing bucket
+ * ```typescript
+ * const assets = Fly.Bucket.lookup({ name: "my-assets" });
+ * ```
+ *
  * @resource
  * @product Bucket
  */
@@ -267,10 +296,29 @@ export class BucketProvisionFailed extends Data.TaggedError("Fly.BucketProvision
 class BucketPending extends Data.TaggedError("Fly.BucketPending")<{
   resourceName: string;
   status: string;
-}> {}
+}> {
+  override get message() {
+    return `Tigris bucket ${this.resourceName} is still ${this.status}`;
+  }
+}
+
+/**
+ * Fly lists an add-on whose Tigris bucket is gone, and Fly's delete
+ * fails on the missing bucket.
+ */
+export class BucketRecordStale extends Data.TaggedError("Fly.BucketRecordStale")<{
+  resourceName: string;
+  reason: string;
+}> {
+  override get message() {
+    return `Fly keeps a stale add-on record for Tigris bucket ${this.resourceName}: ${this.reason}`;
+  }
+}
 
 const TIGRIS = "tigris" as const;
 
+const TIGRIS_ENDPOINT = "https://fly.storage.tigris.dev";
+
 const backoff = Schedule.min([
   Schedule.exponential(Duration.millis(500), 1.5),
   Schedule.spaced(Duration.seconds(5)),
@@ -493,32 +541,213 @@ const waitUntilReady = (name: string, addOnId: string) =>
     Effect.catchTag("Fly.BucketPending", () => findById(addOnId)),
   );
 
-const waitUntilGone = (addOnId: string, name: string) =>
-  Effect.gen(function* () {
-    // Best-effort: Tigris often answers "The specified bucket does not
-    // exist" (untyped UnknownFlyIoError) for a delete that already
-    // succeeded. Never fail the wait on that — only on the add-on still
-    // showing up in list.
-    yield* Effect.result(
-      addons.deleteAddOn({
-        input: addOnId.length > 0 ? { addOnId } : { name, provider: TIGRIS },
+interface TigrisKeys {
+  accessKeyId: Redacted.Redacted<string>;
+  secretAccessKey: Redacted.Redacted<string>;
+  endpoint: string;
+}
+
+/** The bucket's own S3 keys. Fly returns them only from createAddOn. */
+const tigrisKeysOf = (
+  attrs: Pick<Bucket["Attributes"], "accessKeyId" | "secretAccessKey" | "endpoint">,
+): TigrisKeys | undefined =>
+  attrs.accessKeyId !== undefined && attrs.secretAccessKey !== undefined
+    ? {
+        accessKeyId: attrs.accessKeyId,
+        secretAccessKey: attrs.secretAccessKey,
+        endpoint: asString(attrs.endpoint) ?? TIGRIS_ENDPOINT,
+      }
+    : undefined;
+
+const withTigrisKeys = <A, E>(
+  keys: TigrisKeys,
+  operation: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
+) =>
+  operation.pipe(
+    Effect.provide(
+      Layer.mergeAll(
+        fromCredentials(
+          { accessKeyId: keys.accessKeyId, secretAccessKey: keys.secretAccessKey },
+          "auto" as RegionName,
+        ),
+        AwsEndpoint.of(keys.endpoint),
+        FetchHttpClient.layer,
+      ),
+    ),
+  );
+
+/**
+ * Signed HeadBucket. Tigris answers 404 for a name it has no bucket
+ * under and 403 for a bucket the keys don't own. After a delete it can
+ * keep answering 200 to the deleted bucket's own keys for minutes.
+ */
+const tigrisHasBucket = (keys: TigrisKeys, bucketName: string) =>
+  withTigrisKeys(keys, S3.headBucket({ Bucket: bucketName })).pipe(
+    Effect.as(true),
+    Effect.catchTag(["NotFound", "NoSuchBucket"], () => Effect.succeed(false)),
+  );
+
+const requestDelete = (addOnId: string, name: string) =>
+  addons
+    .deleteAddOn({
+      input: addOnId.length > 0 ? { addOnId } : { name, provider: TIGRIS },
+    })
+    .pipe(
+      Effect.as("deleted" as const),
+      Effect.catchTag("TigrisBucketNotFound", () => Effect.succeed("missing" as const)),
+    );
+
+interface DeleteTarget {
+  addOnId: string;
+  /** Fly add-on name. */
+  name: string;
+  /** Tigris bucket name (the add-on name unless Fly said otherwise). */
+  bucketName: string;
+  keys: TigrisKeys | undefined;
+}
+
+const deleteTargetOf = (attrs: Bucket["Attributes"]): DeleteTarget => ({
+  addOnId: attrs.addOnId,
+  name: attrs.name,
+  bucketName: asString(attrs.bucketName) ?? attrs.name,
+  keys: tigrisKeysOf(attrs),
+});
+
+/**
+ * Delete through Fly (which also empties the bucket), then confirm.
+ * With the bucket's keys, Tigris decides (its missing-bucket answer to
+ * the delete, else HeadBucket): Fly's list lags it and can keep a stale
+ * record. Without keys, the add-on must leave Fly's list.
+ * Fails with BucketPending once the confirm runs out; `missing` reports
+ * whether Fly's last delete said Tigris has no such bucket while the
+ * record stayed listed (only without keys).
+ */
+const deleteVerified = (target: DeleteTarget) =>
+  Effect.suspend(() => {
+    const state = { missing: false };
+    return Effect.gen(function* () {
+      // Other delete failures (a bucket still attached to an App, a Fly
+      // 5xx) are transient; the confirm below decides.
+      const requested = yield* Effect.result(requestDelete(target.addOnId, target.name));
+      state.missing = Result.isSuccess(requested) && requested.success === "missing";
+      if (target.keys !== undefined) {
+        // Fly forwards Tigris's own "bucket does not exist" for the delete:
+        // the bucket is gone. HeadBucket can keep answering 200 to the
+        // deleted bucket's keys for minutes after that.
+        if (state.missing) return;
+        if (!(yield* tigrisHasBucket(target.keys, target.bucketName))) return;
+        return yield* new BucketPending({ resourceName: target.name, status: "deleting" });
+      }
+      const still =
+        (target.addOnId.length > 0 ? yield* findById(target.addOnId) : undefined) ??
+        (target.name.length > 0 ? yield* findByName(target.name) : undefined);
+      if (still !== undefined) {
+        return yield* new BucketPending({
+          resourceName: target.name,
+          status: still.status ?? "deleting",
+        });
+      }
+    }).pipe(
+      Effect.retry({
+        while: (e) => e._tag === "Fly.BucketPending",
+        schedule: Schedule.spaced("2 seconds"),
+        times: 20,
       }),
+      Effect.as({ missing: false }),
+      Effect.catchTag("Fly.BucketPending", (pending) =>
+        state.missing && target.keys === undefined
+          ? Effect.succeed({ missing: true })
+          : Effect.fail(pending),
+      ),
     );
-    const still =
-      (yield* findById(addOnId)) ?? (name.length > 0 ? yield* findByName(name) : undefined);
-    if (still !== undefined) {
-      return yield* new BucketPending({
-        resourceName: name,
-        status: still.status ?? "deleting",
-      });
-    }
-  }).pipe(
-    Effect.retry({
-      while: (e) => e._tag === "Fly.BucketPending",
-      schedule: Schedule.spaced("2 seconds"),
-      times: 20,
+  });
+
+const randomBase32 = (length: number) =>
+  Effect.sync(() => {
+    const alphabet = "abcdefghijklmnopqrstuvwxyz234567";
+    return Array.from(crypto.getRandomValues(new Uint8Array(length)), (b) => alphabet[b % 32]).join(
+      "",
+    );
+  });
+
+/**
+ * A throwaway bucket, only for its keys. Its name matches the physical
+ * name shape, so a leaked one is listed and nuked like any other.
+ */
+const helperBucket = Effect.fn(function* (orgSlug: string) {
+  const org = yield* resolveOrganization(orgSlug);
+  if (org === undefined) {
+    return yield* new BucketOrgMissing({ orgSlug });
+  }
+  yield* ensureTos(orgSlug, org.id);
+  const name = `alchemy-fix-${yield* randomBase32(16)}`;
+  const created = yield* addons.createAddOn({
+    input: {
+      type: TIGRIS,
+      name,
+      organizationId: org.id,
+      options: desiredOptions({}),
+    },
+  });
+  return toAttrs(created.addOn, undefined, { name, orgSlug });
+});
+
+/**
+ * Fly keeps an add-on record whose Tigris bucket is gone, and its
+ * delete fails on the missing bucket. Recreate the name in Tigris with a
+ * throwaway bucket's keys so Fly's delete has a bucket to remove.
+ * CreateBucket fails on a name Tigris still holds, so this never touches
+ * a live bucket. A name deleted in the last several minutes stays
+ * blocked (`BucketInaccessible`); the delete fails and a later one
+ * repairs it.
+ */
+const repairStaleRecord = Effect.fn(function* (target: DeleteTarget, orgSlug: string) {
+  yield* Effect.logWarning(
+    `Fly still lists Tigris bucket ${target.name} after Tigris reported it gone; repairing the stale record`,
+  );
+  yield* Effect.scoped(
+    Effect.gen(function* () {
+      const helper = yield* Effect.acquireRelease(helperBucket(orgSlug), (attrs) =>
+        deleteVerified(deleteTargetOf(attrs)).pipe(Effect.ignore),
+      );
+      const keys = tigrisKeysOf(helper);
+      if (keys === undefined) {
+        return yield* new BucketRecordStale({
+          resourceName: target.name,
+          reason: "Fly returned no keys for the temporary repair bucket",
+        });
+      }
+      const recreated = yield* Effect.result(
+        withTigrisKeys(keys, S3.createBucket({ Bucket: target.bucketName })),
+      );
+      if (Result.isFailure(recreated)) {
+        return yield* new BucketRecordStale({
+          resourceName: target.name,
+          reason: `Tigris would not recreate the name (${recreated.failure._tag}); a recently deleted name stays blocked for several minutes, so retry the delete later`,
+        });
+      }
+      const result = yield* deleteVerified({ ...target, keys: undefined });
+      if (result.missing) {
+        return yield* new BucketRecordStale({
+          resourceName: target.name,
+          reason: "Fly's delete still reported a missing bucket after the name was recreated",
+        });
+      }
     }),
   );
+});
+
+/**
+ * Delete and confirm. A stale Fly record is repaired only when there are
+ * no keys to ask Tigris with (nuke, adopted buckets): with keys, Tigris's
+ * 404 already proves the bucket is gone.
+ */
+const waitUntilGone = Effect.fn(function* (attrs: Bucket["Attributes"]) {
+  const target = deleteTargetOf(attrs);
+  const result = yield* deleteVerified(target);
+  if (!result.missing) return;
+  yield* repairStaleRecord(target, attrs.orgSlug ?? (yield* resolveOrgSlug()));
+});
 
 const resolveOrganization = (orgSlug: string) =>
   addons
@@ -582,6 +811,15 @@ export const BucketProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ name }) {
+      const found = yield* findByName(name);
+      if (found === undefined) return undefined;
+      const detail = yield* addons
+        .addOn({ id: found.id, name: found.name ?? name, provider: TIGRIS })
+        .pipe(Effect.catchTag("FlyIoParseError", () => Effect.undefined));
+      return toAttrs(detail ?? found, undefined, { name });
+    }),
+
     read: Effect.fn(function* ({ id, olds, output }) {
       const name = yield* resolveBucketName(id, olds?.name, output?.name);
       const found =
@@ -716,15 +954,8 @@ export const BucketProvider = () =>
     }),
 
     delete: Effect.fn(function* ({ output }) {
-      const addOnId = output.addOnId;
-      const name = output.name;
-      if (addOnId.length === 0 && name.length === 0) return;
-      // Always wait for the add-on to leave the list. A failed
-      // deleteAddOn plus a single list miss is not gone — Tigris
-      // list lags, and a bucket still attached to an App is a
-      // transient error. waitUntilGone retries delete and only
-      // succeeds once list (id and name) is empty.
-      yield* waitUntilGone(addOnId, name);
+      if (output.addOnId.length === 0 && output.name.length === 0) return;
+      yield* waitUntilGone(output);
     }),
   });
 

package/src/Certificate.ts

@@ -97,9 +97,21 @@ export type Certificate = Resource<
     source: CertificateSource;
   },
   never,
-  Providers
+  Providers,
+  CertificateLookup
 >;
 
+/**
+ * Props for {@link Certificate.lookup}: find a certificate this stack
+ * doesn't manage by its App and hostname.
+ */
+export interface CertificateLookup {
+  /** Fly App name the certificate is attached to. */
+  appName: string;
+  /** Hostname the certificate covers. */
+  hostname: string;
+}
+
 /**
  * A Fly.Certificate covers a hostname on an {@link App}. Default
  * `kind` is `"acme"` (Let's Encrypt). `"custom"` uploads a PEM.
@@ -176,6 +188,20 @@ export type Certificate = Resource<
  * });
  * ```
  *
+ * ### Looking up an existing certificate
+ * `Certificate.lookup` references a certificate Alchemy doesn't manage
+ * (added with `fly certs add` or by another stack). It is read during
+ * plan/deploy, never created, updated or deleted.
+ *
+ * **Example:** Read the DNS records Fly expects
+ * ```typescript
+ * const cert = Fly.Certificate.lookup({
+ *   appName: "my-site",
+ *   hostname: "www.example.com",
+ * });
+ * const target = cert.dnsRequirements;
+ * ```
+ *
  * @resource
  * @product Certificate
  */
@@ -423,6 +449,11 @@ export const CertificateProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ appName, hostname }) {
+      const found = yield* getByHostname(appName, hostname);
+      return found === undefined ? undefined : toAttrs(appName, found, hostname);
+    }),
+
     read: Effect.fn(function* ({ olds, output }) {
       const appName = output?.appName ?? appNameOf(olds?.app);
       const hostname = output?.hostname ?? olds?.hostname;

package/src/Credentials.ts

@@ -24,11 +24,14 @@ export {
  */
 export const bindFlyApiToken = (): Effect.Effect<void, never, Credentials> =>
   Effect.gen(function* () {
+    // Bound as Redacted so a Service that owns its App stores the token
+    // as an App secret, not plain Machine env. The runtime reads it back
+    // with `CredentialsFromEnv`.
     const token = globalThis.__ALCHEMY_RUNTIME__
-      ? ""
+      ? Redacted.make("")
       : yield* Credentials.pipe(
           Effect.flatMap((resolve) => resolve),
-          Effect.map((cfg) => Redacted.value(cfg.apiKey)),
+          Effect.map((cfg) => cfg.apiKey),
           // Binding initialization cannot fail; the engine reports this
           // defect as `CredentialsRequired`.
           orDieCredentialsUnavailable("Fly"),
@@ -44,9 +47,10 @@ export const bindFlyApiToken = (): Effect.Effect<void, never, Credentials> =>
  * `Credentials`, and the binding must use them — a laptop deploy has no
  * `FLY_API_TOKEN` in its env once the token lives in the Alchemy profile.
  * Inside a deployed Machine there is no profile; `bindFlyApiToken`
- * has already `RuntimeContext.set` the org token, which Platform copies
- * into Machine env as `FLY_API_TOKEN`. So: reuse the ambient
- * `Credentials` when present, otherwise read the env.
+ * has already `RuntimeContext.set` the org token, which reaches the
+ * Machine as `FLY_API_TOKEN` (an App secret, or Machine env in a shared
+ * App). So: reuse the ambient `Credentials` when present, otherwise read
+ * it with {@link CredentialsFromEnv}.
  */
 export const CredentialsFromAmbientOrEnv: Layer.Layer<Credentials> = Layer.effect(
   Credentials,

package/src/IpAssignment.ts

@@ -85,9 +85,21 @@ export type IpAssignment = Resource<
     createdAt: string | undefined;
   },
   never,
-  Providers
+  Providers,
+  IpAssignmentLookup
 >;
 
+/**
+ * Props for {@link IpAssignment.lookup}: find an address this stack
+ * doesn't manage by its App and IP.
+ */
+export interface IpAssignmentLookup {
+  /** Fly App name the address is assigned to. */
+  appName: string;
+  /** The allocated address. */
+  ip: string;
+}
+
 const resolveIpAssignmentProps = (
   props: IpAssignmentProps | Effect.Effect<IpAssignmentProps, never, Providers>,
 ): Effect.Effect<IpAssignmentProps, never, Providers> =>
@@ -247,6 +259,19 @@ const IpAssignmentResource = Resource<IpAssignment>("Fly.IpAssignment");
  * );
  * ```
  *
+ * ### Looking up an existing address
+ * `IpAssignment.lookup` references an address Alchemy doesn't manage
+ * (allocated with `fly ips allocate-v4` or by another stack). It is read
+ * during plan/deploy, never allocated or released.
+ *
+ * **Example:** Reference an existing address
+ * ```typescript
+ * const ip = Fly.IpAssignment.lookup({
+ *   appName: "my-site",
+ *   ip: "2a09:8280:1::1",
+ * });
+ * ```
+ *
  * @resource
  * @product App
  */
@@ -439,6 +464,11 @@ export const IpAssignmentProvider = () =>
       return undefined;
     }),
 
+    lookup: Effect.fn(function* ({ appName, ip }) {
+      const found = yield* findByIp(appName, ip);
+      return found?.ip === undefined ? undefined : toAttrs(appName, found);
+    }),
+
     read: Effect.fn(function* ({ olds, output }) {
       const appName = output?.appName ?? appNameOf(olds?.app);
       if (appName === undefined) return undefined;