Flyio Security Basics

---
name: flyio-security-basics
description: 'Apply Fly.io security best practices for secrets management, private
  networking,

  TLS certificates, and deploy token scoping.

  Trigger: "fly.io security", "fly secrets", "fly.io TLS", "fly.io private network".

  '
allowed-tools: Read, Write, Edit, Bash(fly:*)
version: 1.7.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- edge-compute
- flyio
compatibility: Designed for Claude Code
---
# Fly.io Security Basics

## Overview

Fly.io deploys applications to edge locations worldwide using Firecracker microVMs. Security concerns center on deploy token scoping (org-wide vs per-app), secrets management (encrypted at rest, injected as env vars), private networking via WireGuard mesh (6PN), and TLS certificate management. A leaked deploy token can push arbitrary code to production machines across all regions.

## Prerequisites

- A named security owner, app/organization access inventory, secret-manager integration, and recurring access-review cadence.
- Approved network, region, TLS, logging, and incident/revocation policies plus synthetic staging fixtures.

## Instructions

1. Use app-scoped deploy tokens and separate identities per environment; never place tokens in code, tickets, terminal captures, or debug bundles.
2. Restrict private services and secrets to the minimum set of machines and roles, with explicit network boundaries and access review.
3. Verify incoming signed events before processing, log opaque IDs only, and make downstream actions idempotent.
4. Monitor for unauthorized deployment, secret, region, or certificate changes and rotate/revoke credentials immediately after suspected exposure.

## Output

Maintain a security receipt with identity scope, secret reference, policy version, access-review date, verification/rotation result, owner, and redacted incident state. Never include tokens, configuration secrets, or user data.

## Examples

Create a disposable staging app using a scoped token, attempt an unauthorized app operation, and verify it is denied. Rotate the token, confirm the old credential fails, and retain only the redacted policy and control outcome.

## API Key Management

```typescript
function validateFlyToken(): void {
  const token = process.env.FLY_API_TOKEN;
  if (!token) {
    throw new Error("Missing FLY_API_TOKEN — use `fly tokens create deploy -a <app>`");
  }
  // Never log tokens; log only token type for debugging
  const isDeployToken = token.startsWith("FlyV1");
  console.log("Fly.io token loaded, type:", isDeployToken ? "deploy" : "personal");
}
```

## Webhook Signature Verification

```typescript
import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyFlyWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-fly-signature"] as string;
  const secret = process.env.FLY_WEBHOOK_SECRET!;
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}
```

## Input Validation

```typescript
import { z } from "zod";

const FlyDeploySchema = z.object({
  app_name: z.string().regex(/^[a-z0-9-]+$/).max(63),
  region: z.enum(["iad", "ord", "lax", "sjc", "ams", "lhr", "nrt", "syd", "gru"]),
  image: z.string().regex(/^registry\..+\/.+:.+$/),
  vm_size: z.enum(["shared-cpu-1x", "shared-cpu-2x", "performance-1x", "performance-2x"]).optional(),
  min_machines: z.number().int().min(0).max(20).optional(),
});

function validateDeployConfig(data: unknown) {
  return FlyDeploySchema.parse(data);
}
```

## Data Protection

```typescript
const FLY_SENSITIVE_FIELDS = ["fly_api_token", "deploy_token", "db_password", "wireguard_private_key", "tls_private_key"];

function redactFlyLog(record: Record<string, unknown>): Record<string, unknown> {
  const redacted = { ...record };
  for (const field of FLY_SENSITIVE_FIELDS) {
    if (field in redacted) redacted[field] = "[REDACTED]";
  }
  return redacted;
}
```

## Security Checklist

- [ ] All sensitive values in `fly secrets`, never in `[env]` section of fly.toml
- [ ] Deploy tokens scoped per-app, not org-wide
- [ ] `force_https = true` set in fly.toml `[http_service]`
- [ ] Internal services use `.internal` DNS with no public ports
- [ ] WireGuard keys rotated and unused tunnels removed
- [ ] Secrets rotated on schedule (triggers rolling restart)
- [ ] CI/CD uses deploy-scoped tokens, not personal tokens
- [ ] Container images scanned before deployment

## Error Handling

| Vulnerability | Risk | Mitigation |
|---|---|---|
| Leaked deploy token | Arbitrary code deployed to production | Per-app scoped tokens + rotation |
| Secrets in fly.toml `[env]` | Plaintext credentials in version control | Use `fly secrets set` exclusively |
| Open internal ports | Services exposed to public internet | `.internal` DNS + NetworkPolicy |
| Org-wide token in CI | All apps in org compromised via CI breach | Deploy-scoped tokens per pipeline |
| Expired TLS certificates | MITM attacks on custom domains | Automated Let's Encrypt renewal |

## Resources

- [Fly Secrets](https://fly.io/docs/reference/secrets/)
- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)

## Next Steps

See `flyio-prod-checklist`.