import type { SecretKey as FlySecretKey } from "@distilled.cloud/fly-io/machines";
import * as machines from "@distilled.cloud/fly-io/machines";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, 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 Schedule from "effect/Schedule";
import { App, listOwnedApps } from "./App.ts";
import {
createFlyVolumeName,
matchesAlchemyPhysicalName,
sanitizeFlyVolumeName,
} 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 SecretKeyProps {
/**
* Parent Fly App. Changing it replaces the secret key.
*/
app: Ref<App>;
/**
* Secret key name, unique per App. If omitted, a unique name is generated
* from the stack, stage and logical ID (the ownership stamp). Changing it
* replaces the key.
*/
name?: string;
/**
* Fly key type (`nacl_sign`, `nacl_box`, `hs256`, `hs384`, `hs512`,
* `xaes256gcm`, `nacl_auth`, `nacl_secretbox`, `es256`). Changing it
* replaces the key.
*/
type?: string;
/**
* Raw key material. If omitted, Fly generates a key via
* `generateSecretKey`. If set, the key is created or updated with
* `setSecretKey`. Never persisted in state.
*/
value?: ReadonlyArray<number>;
}
export type SecretKey = Resource<
"Fly.SecretKey",
SecretKeyProps,
{
/** Parent Fly App name. */
appName: string;
/** Secret key name (unique per App). */
name: string;
/** Observed Fly key type. */
type: string | undefined;
/** Public key (base64), when the type has one. Never private material. */
publicKey: string | undefined;
/** RFC3339 creation timestamp. */
createdAt: string | undefined;
/** RFC3339 last-update timestamp. */
updatedAt: string | undefined;
},
never,
Providers
>;
const resolveSecretKeyProps = (
props: SecretKeyProps | Effect.Effect<SecretKeyProps, never, Providers>,
): Effect.Effect<SecretKeyProps, 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 SecretKeyResource = Resource<SecretKey>("Fly.SecretKey");
/**
* A Fly.SecretKey is an App KMS key, not an env secret. Generate a
* random key or set raw material. Private bytes never appear in
* attributes.
*
* Use it at runtime with {@link Encrypt}, {@link Decrypt}, {@link Sign},
* and {@link Verify}. Generate, set, and delete stay on this resource.
*
* @see https://docs.machines.dev/secrets/Secretkeys_list
*
* ### Generate a key
* Omit `value` and Fly generates a key via `generateSecretKey`. `type`
* is Fly's key type (`nacl_sign`, `nacl_box`, `nacl_secretbox`,
* `hs256`, `hs384`, `hs512`, `xaes256gcm`, `nacl_auth`, `es256`, …).
*
* **Example:** Signing key
* ```typescript
* export const Signing = Fly.SecretKey("Signing", {
* app: Site,
* type: "nacl_sign",
* });
* ```
*
* :::caution[Changing `app`, `name`, or `type` replaces the key]
* The new key is created. The old one is deleted. Ciphertext from the
* old key will not decrypt.
* :::
*
* ### Set raw material
* Pass `value` as bytes. The key is created or updated with
* `setSecretKey`. Never persisted in state.
*
* **Example:** HS256
* ```typescript
* const hmac = yield* Fly.SecretKey("Hmac", {
* app: Site,
* type: "hs256",
* value: hmacBytes,
* });
* ```
*
* ### Encrypt
* Bind {@link Encrypt} to a box/secretbox/AEAD key. Provide
* {@link EncryptHttp}. Optional `associatedData` is AEAD associated
* data.
*
* Fly crypto ops need a KMS token. Org API tokens are typed
* `Forbidden`. Encrypt and sign from a {@link Service}, not a laptop
* Action.
*
* **Example:** Encrypt a payload
* ```typescript
* const encrypt = yield* Fly.Encrypt(Box);
* const { ciphertext } = yield* encrypt({
* plaintext: new TextEncoder().encode("attack at dawn"),
* });
* ```
*
* ### Decrypt
* Bind {@link Decrypt} to the same key. Plaintext comes back
* `Redacted`. Unwrap with `Redacted.value`. `associatedData` must
* match encryption. Provide {@link DecryptHttp}.
*
* **Example:** Decrypt a payload
* ```typescript
* const decrypt = yield* Fly.Decrypt(Box);
* const { plaintext } = yield* decrypt({ ciphertext });
* const bytes = Redacted.value(plaintext);
* ```
*
* ### Sign
* Bind {@link Sign} to a signing key (`nacl_sign`, `hs256`, `es256`,
* …). The private key never leaves Fly KMS. Provide {@link SignHttp}.
*
* **Example:** Sign a payload
* ```typescript
* const sign = yield* Fly.Sign(Signing);
* const { signature } = yield* sign({
* plaintext: new TextEncoder().encode("release-manifest-v1"),
* });
* ```
*
* ### Verify
* Bind {@link Verify} to the same key. A bad signature is a typed
* error from the Machines API. Provide {@link VerifyHttp}.
*
* **Example:** Verify a signature
* ```typescript
* const verify = yield* Fly.Verify(Signing);
* const { valid } = yield* verify({ plaintext, signature });
* ```
*
* @resource
* @product Secret Key
*/
export const SecretKey: typeof SecretKeyResource = Object.assign(
(id: string, props: SecretKeyProps | Effect.Effect<SecretKeyProps, never, Providers>) =>
SecretKeyResource(id, resolveSecretKeyProps(props)),
SecretKeyResource,
);
export class SecretKeyNotCreated extends Data.TaggedError("Fly.SecretKeyNotCreated")<{
appName: string;
secretName: string;
}> {}
export class SecretKeyAppRequired extends Data.TaggedError("Fly.SecretKeyAppRequired")<{
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 resolveName = (id: string, name: string | undefined, existing?: string) =>
Effect.gen(function* () {
if (name !== undefined) return sanitizeFlyVolumeName(name);
if (existing !== undefined) return existing;
return yield* createFlyVolumeName(id);
});
const toAttrs = (
appName: string,
key: FlySecretKey,
fallbackName: string,
): SecretKey["Attributes"] => ({
appName,
name: key.name ?? fallbackName,
type: key.type,
publicKey: key.public_key,
createdAt: key.created_at,
updatedAt: key.updated_at,
});
const getByName = (appName: string, secretName: string) =>
machines
.getSecretKey({
app_name: appName,
secret_name: secretName,
})
.pipe(Effect.catchTag("NotFound", () => Effect.undefined));
const listKeys = (appName: string) =>
machines.listSecretKeys({ app_name: appName }).pipe(
Effect.map((res) => res.secret_keys ?? []),
Effect.catchTag(["NotFound", "Forbidden"], () => Effect.succeed([])),
);
const putKey = (input: {
appName: string;
secretName: string;
type: string | undefined;
value: ReadonlyArray<number> | undefined;
}) => {
if (input.value !== undefined) {
return machines.setSecretKey({
app_name: input.appName,
secret_name: input.secretName,
type: input.type,
value: [...input.value],
});
}
return machines.generateSecretKey({
app_name: input.appName,
secret_name: input.secretName,
type: input.type,
});
};
const valuesEqual = (
left: ReadonlyArray<number> | undefined,
right: ReadonlyArray<number> | undefined,
): boolean => {
if (left === undefined && right === undefined) return true;
if (left === undefined || right === undefined) return false;
return deepEqual(left, right);
};
export const SecretKeyProvider = () =>
Provider.succeed(SecretKey, {
stables: ["appName", "name", "type", "publicKey", "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 ? sanitizeFlyVolumeName(news.name) : output.name;
const nameChanged = desiredName !== output.name;
const nextApp = appNameOf(news.app);
const appChanged = nextApp !== undefined && nextApp !== output.appName;
const typeChanged =
news.type !== undefined && output.type !== undefined && news.type !== output.type;
if (nameChanged || appChanged || typeChanged) {
return {
action: "replace" as const,
// Same (app, name) cannot hold two types — delete 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) =>
listKeys(app.appName).pipe(
Effect.map((keys) =>
keys.flatMap((key) => {
const name = key.name;
if (!matchesAlchemyPhysicalName(name)) return [];
return [toAttrs(app.appName, key, name ?? "")];
}),
),
),
{ concurrency: 8 },
);
return rows.flat();
}),
reconcile: Effect.fn(function* ({ id, news, olds, output }) {
const props = news ?? ({} as SecretKeyProps);
const appName = appNameOf(props.app) ?? output?.appName;
if (appName === undefined) {
return yield* new SecretKeyAppRequired({
message: "SecretKey requires a resolved Fly.App",
});
}
const name = yield* resolveName(id, props.name, output?.name);
// 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);
}
if (current === undefined) {
yield* putKey({
appName,
secretName: name,
type: props.type,
value: props.value,
}).pipe(Effect.catchTag("Conflict", () => Effect.void));
current = yield* getByName(appName, name);
}
if (current === undefined) {
return yield* new SecretKeyNotCreated({ appName, secretName: name });
}
// Sync — re-set when the caller supplied new material. Observed
// cloud never returns private bytes; `olds.value` is only a hint.
const desiredValue = props.value;
if (desiredValue !== undefined) {
const previousValue = olds?.value;
const shouldSet = previousValue === undefined || !valuesEqual(previousValue, desiredValue);
if (shouldSet) {
yield* putKey({
appName,
secretName: name,
type: props.type ?? current.type,
value: desiredValue,
}).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
.deleteSecretKey({
app_name: output.appName,
secret_name: output.name,
})
.pipe(Effect.catchTag("NotFound", () => Effect.void));
yield* getByName(output.appName, output.name).pipe(
Effect.map((key) => key === undefined),
Effect.repeat({
schedule: Schedule.spaced("1 second"),
until: (gone) => gone,
times: 8,
}),
);
}),
});