SecretKey

Source: src/Fly/SecretKey.ts

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 Encrypt, Decrypt, Sign, and Verify. Generate, set, and delete stay on this resource.

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, …).

export const Signing = Fly.SecretKey("Signing", {
  app: Site,
  type: "nacl_sign",
});

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.

const hmac = yield* Fly.SecretKey("Hmac", {
  app: Site,
  type: "hs256",
  value: hmacBytes,
});

Encrypt

Bind Encrypt to a box/secretbox/AEAD key. Provide 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 Service, not a laptop Action.

const encrypt = yield* Fly.Encrypt(Box);
const { ciphertext } = yield* encrypt({
  plaintext: new TextEncoder().encode("attack at dawn"),
});

Decrypt

Bind Decrypt to the same key. Plaintext comes back Redacted. Unwrap with Redacted.value. associatedData must match encryption. Provide DecryptHttp.

const decrypt = yield* Fly.Decrypt(Box);
const { plaintext } = yield* decrypt({ ciphertext });
const bytes = Redacted.value(plaintext);

Sign

Bind Sign to a signing key (nacl_sign, hs256, es256, …). The private key never leaves Fly KMS. Provide SignHttp.

const sign = yield* Fly.Sign(Signing);
const { signature } = yield* sign({
  plaintext: new TextEncoder().encode("release-manifest-v1"),
});

Verify

Bind Verify to the same key. A bad signature is a typed error from the Machines API. Provide VerifyHttp.

const verify = yield* Fly.Verify(Signing);
const { valid } = yield* verify({ plaintext, signature });