@cardelli/ambit 0.2.3 → 0.3.1

package/README.md

@@ -67,17 +67,38 @@ Open `http://my-crazy-site.lab`. It works for you and nobody else.
 
 ### `ambit create <network>`
 
-This is the first command you run, it sets up your private network: a named slice of the cloud that only your devices can reach. Under the hood it handles Fly.io and Tailscale authentication, deploys the router, sets up DNS, and configures your local machine to accept the new routes.
-
-| Flag                   | Description                                                |
-| ---------------------- | ---------------------------------------------------------- |
-| `--org <org>`          | Fly.io organization slug                                   |
-| `--region <region>`    | Fly.io region (default: `iad`)                             |
-| `--api-key <key>`      | Tailscale API access token (tskey-api-...)                 |
-| `--tag <tag>`          | Tailscale ACL tag for the router (default: `tag:ambit-<network>`) |
-| `--no-auto-approve`    | Skip waiting for router and approving routes               |
-| `-y`, `--yes`          | Skip confirmation prompts                                  |
-| `--json`               | Machine-readable JSON output (implies `--no-auto-approve`) |
+This is the first command you run, it sets up your private network: a named slice of the cloud that only your devices can reach. Under the hood it handles Fly.io and Tailscale authentication, deploys the router, sets up DNS, configures your local machine to accept the new routes, and automatically adds the router's tag to your Tailscale ACL policy.
+
+| Flag                | Description                                                                 |
+| ------------------- | --------------------------------------------------------------------------- |
+| `--org <org>`       | Fly.io organization slug                                                    |
+| `--region <region>` | Fly.io region (default: `iad`)                                              |
+| `--api-key <key>`   | Tailscale API access token (tskey-api-...)                                  |
+| `--tag <tag>`       | Tailscale ACL tag for the router (default: `tag:ambit-<network>`)           |
+| `--manual`          | Skip automatic Tailscale ACL configuration (tagOwners + autoApprovers)      |
+| `--no-auto-approve` | Skip waiting for router and approving routes                                |
+| `-y`, `--yes`       | Skip confirmation prompts                                                   |
+| `--json`            | Machine-readable JSON output (implies `--no-auto-approve`)                  |
+
+### `ambit share <network> <member> [<member>...]`
+
+Grants one or more members access to a network by adding two ACL rules per member: one for DNS (so they can resolve `*.<network>` names) and one for the subnet (so they can reach apps). All members are validated before any changes are made. The command is idempotent — safe to re-run.
+
+Each member must be one of:
+- `group:<name>` — a Tailscale group
+- `tag:<name>` — a device tag
+- `autogroup:<name>` — a built-in Tailscale group (e.g. `autogroup:member`)
+- A valid email address — a specific Tailscale user
+
+```bash
+npx @cardelli/ambit share browsers group:team
+npx @cardelli/ambit share browsers group:team alice@example.com group:contractors
+```
+
+| Flag          | Description              |
+| ------------- | ------------------------ |
+| `--org <org>` | Fly.io organization slug |
+| `--json`      | Machine-readable JSON    |
 
 ### `ambit deploy <app>.<network>`
 
@@ -173,11 +194,12 @@ Lists all discovered routers across networks in a table showing the network name
 
 ### `ambit destroy network <name>`
 
-Tears down a network: destroys the router, cleans up DNS, and removes the Tailscale device. If there are workload apps still on the network, ambit warns you before proceeding. Reminds you to clean up any ACL entries you added.
+Tears down a network: destroys the router, cleans up DNS, removes the Tailscale device, and automatically removes the router's tag from your Tailscale ACL policy (tagOwners and autoApprovers). If there are workload apps still on the network, ambit warns you before proceeding.
 
 | Flag              | Description                    |
 | ----------------- | ------------------------------ |
 | `--org <org>`     | Fly.io organization slug       |
+| `--manual`        | Skip automatic Tailscale ACL cleanup (tagOwners + autoApprovers) |
 | `-y`, `--yes`     | Skip confirmation prompts      |
 | `--json`          | Machine-readable JSON output   |
 
@@ -218,20 +240,12 @@ Checks app health: verifies the app is deployed and running, then checks the rou
 
 ## Access Control
 
-Ambit doesn't touch your Tailscale ACL policy. After creating a router, it prints the exact policy entries you need so you can control who on your tailnet can reach which networks. By default, if you haven't restricted anything, all your devices can reach everything.
+By default, `ambit create` automatically adds the router's tag to your Tailscale ACL policy (`tagOwners` and `autoApprovers`). `ambit destroy network` automatically removes them. Pass `--manual` to either command to skip this and manage the policy yourself — useful if your API token lacks ACL write permission (`policy_file` scope).
 
-If you want to lock it down, two rules do the job — one for DNS queries and one for data traffic:
+If you want to lock down which users can reach which networks, two rules do the job — one for DNS queries and one for data traffic:
 
 ```jsonc
 {
-  "tagOwners": {
-    "tag:ambit-infra": ["autogroup:admin"]
-  },
-  "autoApprovers": {
-    "routes": {
-      "fdaa:X:XXXX::/48": ["tag:ambit-infra"]
-    }
-  },
   "acls": [
     {
       "action": "accept",
@@ -243,6 +257,8 @@ If you want to lock it down, two rules do the job — one for DNS queries and on
 }
 ```
 
+These `acls` entries are never touched automatically — ambit only manages `tagOwners` and `autoApprovers`.
+
 ## Multiple Networks
 
 You can create as many networks as you want, and each one gets its own TLD on your tailnet. The SOCKS proxy on each router means containers on one network can reach services on another by going through the tailnet, so a browser on your `browsers` network can connect to a database on your `infra` network.

package/esm/cli/commands/create/index.js

@@ -9,12 +9,12 @@ import { runMachine } from "../../../lib/machine.js";
 import { registerCommand } from "../../mod.js";
 import { getRouterTag } from "../../../util/naming.js";
 import { isPublicTld } from "../../../util/guard.js";
-import { createFlyProvider, } from "../../../providers/fly.js";
+import { createFlyProvider } from "../../../providers/fly.js";
 import { createTailscaleProvider, } from "../../../providers/tailscale.js";
 import { getCredentialStore } from "../../../util/credentials.js";
-import { FLY_PRIVATE_SUBNET, TAILSCALE_API_KEY_PREFIX, } from "../../../util/constants.js";
+import { TAILSCALE_API_KEY_PREFIX } from "../../../util/constants.js";
 import { resolveOrg } from "../../../util/resolve.js";
-import { isAutoApproverConfigured, isTagOwnerConfigured } from "../../../util/tailscale-local.js";
+import { assertAdditivePatch, isAutoApproverConfigured, isTagOwnerConfigured, patchTagOwner, } from "../../../util/tailscale-local.js";
 import { createTransition, hydrateCreate, reportSkipped, } from "./machine.js";
 // =============================================================================
 // Stage 1: Fly.io Configuration
@@ -34,6 +34,13 @@ const stageFlyConfig = async (out, opts) => {
 // =============================================================================
 // Stage 2: Tailscale Configuration
 // =============================================================================
+const handleAclSetFailure = (out, result, action) => {
+    if (result.status === 403) {
+        out.err(`${action}: Permission Denied (HTTP 403)`);
+        return out.die("Your API Token Lacks ACL Write Permission. Re-run with --manual to Skip ACL Changes");
+    }
+    return out.die(`${action}: ${result.error ?? `HTTP ${result.status}`}`);
+};
 const stageTailscaleConfig = async (out, opts) => {
     out.header("Step 2: Tailscale Configuration").blank();
     const credentials = getCredentialStore();
@@ -63,9 +70,26 @@ const stageTailscaleConfig = async (out, opts) => {
     validateSpinner.success("API Access Token Validated");
     await credentials.setTailscaleApiKey(apiKey);
     const tagOwnerSpinner = out.spinner(`Checking tagOwners for ${opts.tag}`);
-    const policy = await tailscale.acl.getPolicy();
+    let policy = await tailscale.acl.getPolicy();
     const hasTagOwner = isTagOwnerConfigured(policy, opts.tag);
-    if (!hasTagOwner) {
+    if (!hasTagOwner && !opts.manual && policy) {
+        tagOwnerSpinner.stop();
+        const beforeTagOwner = policy;
+        policy = patchTagOwner(policy, opts.tag);
+        assertAdditivePatch(beforeTagOwner, policy);
+        const validateTagOwner = await tailscale.acl.validatePolicy(policy);
+        if (!validateTagOwner.ok) {
+            return handleAclSetFailure(out, validateTagOwner, `Validating tagOwners patch for ${opts.tag}`);
+        }
+        const patchSpinner = out.spinner(`Adding ${opts.tag} to tagOwners`);
+        const result = await tailscale.acl.setPolicy(policy);
+        if (!result.ok) {
+            patchSpinner.fail(`Adding ${opts.tag} to tagOwners`);
+            return handleAclSetFailure(out, result, `Adding ${opts.tag} to tagOwners`);
+        }
+        patchSpinner.success(`Added ${opts.tag} to tagOwners`);
+    }
+    else if (!hasTagOwner) {
         tagOwnerSpinner.fail(`${opts.tag} Not Set Up Yet`);
         out.blank()
             .text(`  You need to grant yourself permission to create the "${opts.network}"`)
@@ -80,22 +104,24 @@ const stageTailscaleConfig = async (out, opts) => {
             .blank();
         return out.die(`Set Up ${opts.tag} in Tailscale, Then Try Again`);
     }
-    tagOwnerSpinner.success(`${opts.tag} Found in Tailscale ACL`);
-    if (opts.json) {
+    else {
+        tagOwnerSpinner.success(`${opts.tag} Found in Tailscale ACL`);
+    }
+    if (opts.manual && opts.json) {
         const approverSpinner = out.spinner(`Checking autoApprovers for ${opts.tag}`);
         const hasApprover = isAutoApproverConfigured(policy, opts.tag);
         if (!hasApprover) {
             approverSpinner.fail(`Auto-approve Not Configured for ${opts.tag}`);
             out.blank()
-                .text("  In JSON mode, ambit can't interactively approve the router's")
-                .text(`  network connections. You can set this up from the Tailscale dashboard:`)
+                .text("  In --manual --json mode, ambit can't interactively approve the")
+                .text("  router's subnet routes. Set up autoApprovers first:")
                 .link("  https://login.tailscale.com/admin/acls/visual/auto-approvers")
-                .dim(`  Route: ${FLY_PRIVATE_SUBNET}  Owner: ${opts.tag}`)
+                .dim(`  Route: <subnet>/48  Owner: ${opts.tag}`)
                 .blank()
-                .dim("  Or you can do it manually with this JSON config:")
-                .dim(`    "autoApprovers": { "routes": { "${FLY_PRIVATE_SUBNET}": ["${opts.tag}"] } }`)
+                .dim("  Or in the ACL file:")
+                .dim(`    "autoApprovers": { "routes": { "<subnet>/48": ["${opts.tag}"] } }`)
                 .blank();
-            return out.die(`Set Up Auto-approve for ${opts.tag} to Use --json`);
+            return out.die(`Set Up Auto-approve for ${opts.tag} to Use --manual --json`);
         }
         approverSpinner.success(`Auto-approve Configured for ${opts.tag}`);
     }
@@ -194,7 +220,8 @@ const stageSummary = async (out, fly, tailscale, ctx, opts) => {
             .blank()
             .dim("     You can do this from the Tailscale dashboard:")
             .link("     https://login.tailscale.com/admin/acls/visual/general-access-rules")
-            .dim(`     Source: group:YOUR_GROUP  Destination: ${opts.tag}:*`)
+            .dim(`     Source: group:YOUR_GROUP    Destination: ${opts.tag}:53`)
+            .dim(`     Source: group:YOUR_GROUP    Destination: ${ctx.subnet}:*`)
             .blank()
             .dim("     Or you can do it manually with this JSON config:")
             .dim(`     {"action": "accept", "src": ["group:YOUR_GROUP"], "dst": ["${opts.tag}:53"]}`)
@@ -214,7 +241,7 @@ const stageSummary = async (out, fly, tailscale, ctx, opts) => {
 const create = async (argv) => {
     const opts = {
         string: ["org", "region", "api-key", "tag"],
-        boolean: ["help", "yes", "json", "no-auto-approve"],
+        boolean: ["help", "yes", "json", "no-auto-approve", "manual"],
         alias: { y: "yes" },
     };
     const args = parseArgs(argv, opts);
@@ -231,7 +258,8 @@ ${bold("OPTIONS")}
   --region <region>   Fly.io region (default: iad)
   --api-key <key>     Tailscale API access token (tskey-api-...)
   --tag <tag>         Tailscale ACL tag for the router (default: tag:ambit-<network>)
-  --no-auto-approve        Skip waiting for router and approving routes
+  --manual            Skip automatic Tailscale ACL configuration (tagOwners + autoApprovers)
+  --no-auto-approve   Skip waiting for router and approving routes
   -y, --yes           Skip confirmation prompts
   --json              Output as JSON (implies --no-auto-approve)
 
@@ -241,9 +269,14 @@ ${bold("DESCRIPTION")}
 
     my-app.${args._[0] || "<network>"} resolves to my-app.flycast
 
+  By default, ambit auto-configures your Tailscale ACL policy (tagOwners
+  and autoApprovers). Use --manual if your API token lacks ACL write
+  permission or you prefer to manage the policy yourself.
+
 ${bold("EXAMPLES")}
   ambit create browsers
   ambit create browsers --org my-org --region sea
+  ambit create browsers --manual
 `);
         return;
     }
@@ -257,7 +290,8 @@ ${bold("EXAMPLES")}
         return out.die(`"${network}" Is a Public TLD and Cannot Be Used as a Network Name`);
     }
     const tag = args.tag || getRouterTag(network);
-    const shouldApprove = !(args["no-auto-approve"] || args.json);
+    const manual = !!args.manual;
+    const shouldApprove = !manual || !(args["no-auto-approve"] || args.json);
     out.blank()
         .header("=".repeat(50))
         .header(`  ambit Create: ${network}`)
@@ -270,6 +304,7 @@ ${bold("EXAMPLES")}
     });
     const tailscale = await stageTailscaleConfig(out, {
         json: args.json,
+        manual,
         apiKey: args["api-key"],
         tag,
         network,
@@ -280,6 +315,7 @@ ${bold("EXAMPLES")}
         region,
         tag,
         shouldApprove,
+        manual,
     });
 };
 // =============================================================================

package/esm/cli/commands/create/machine.d.ts

@@ -3,7 +3,7 @@ import { Result } from "../../../lib/result.js";
 import { type FlyProvider } from "../../../providers/fly.js";
 import type { TailscaleProvider } from "../../../providers/tailscale.js";
 import type { TailscaleDevice } from "../../../schemas/tailscale.js";
-export type CreatePhase = "create_app" | "deploy_router" | "await_device" | "approve_routes" | "configure_dns" | "accept_routes" | "complete";
+export type CreatePhase = "create_app" | "deploy_router" | "approve_routes" | "configure_dns" | "accept_routes" | "complete";
 export type CreateResult = {
     network: string;
     router: {
@@ -22,6 +22,7 @@ export interface CreateCtx {
     region: string;
     tag: string;
     shouldApprove: boolean;
+    manual: boolean;
     appName: string;
     routerId: string;
     device?: TailscaleDevice;

package/esm/cli/commands/create/machine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/create/machine.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAQhD,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AASnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAOrE,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,UAAU,CAAC;AAMf,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACxD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,WAAW,CAAC;IACjB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,eAAO,MAAM,aAAa,GACxB,KAAK,MAAM,CAAC,YAAY,CAAC,EACzB,YAAY,WAAW,SAMxB,CAAC;AAMF,eAAO,MAAM,aAAa,GACxB,KAAK,SAAS,KACb,OAAO,CAAC,WAAW,CA4BrB,CAAC;AAMF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,WAAW,EAClB,KAAK,SAAS,KACb,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAgH7B,CAAC"}
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/create/machine.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAQhD,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAW7E,OAAO,KAAK,EAAgB,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAOrE,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,UAAU,CAAC;AAMf,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACxD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,WAAW,CAAC;IACjB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAcD,eAAO,MAAM,aAAa,GACxB,KAAK,MAAM,CAAC,YAAY,CAAC,EACzB,YAAY,WAAW,SAMxB,CAAC;AAMF,eAAO,MAAM,aAAa,GACxB,KAAK,SAAS,KACb,OAAO,CAAC,WAAW,CA4BrB,CAAC;AAMF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,WAAW,EAClB,KAAK,SAAS,KACb,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CA6K7B,CAAC"}

package/esm/cli/commands/create/machine.js

@@ -5,9 +5,9 @@ import { randomId } from "../../../lib/cli.js";
 import { Result } from "../../../lib/result.js";
 import { extractSubnet } from "../../../util/fly-transforms.js";
 import { ROUTER_DOCKER_DIR, SECRET_NETWORK_NAME, SECRET_ROUTER_ID, SECRET_TAILSCALE_AUTHKEY, } from "../../../util/constants.js";
-import { FlyDeployError, } from "../../../providers/fly.js";
+import { FlyDeployError } from "../../../providers/fly.js";
 import { getRouterAppName } from "../../../util/naming.js";
-import { enableAcceptRoutes, isAcceptRoutesEnabled, isAutoApproverConfigured, isTailscaleInstalled, waitForDevice, } from "../../../util/tailscale-local.js";
+import { assertAdditivePatch, enableAcceptRoutes, isAcceptRoutesEnabled, isAutoApproverConfigured, isTailscaleInstalled, patchAutoApprover, waitForDevice, } from "../../../util/tailscale-local.js";
 import { findRouterApp, getRouterMachineInfo } from "../../../util/discovery.js";
 // =============================================================================
 // Phase Labels
@@ -15,7 +15,6 @@ import { findRouterApp, getRouterMachineInfo } from "../../../util/discovery.js"
 const CREATE_PHASES = [
     { phase: "create_app", label: "Fly App Created" },
     { phase: "deploy_router", label: "Router Deployed" },
-    { phase: "await_device", label: "Router in Tailnet" },
     { phase: "approve_routes", label: "Routes Approved" },
     { phase: "configure_dns", label: "Split DNS Configured" },
     { phase: "accept_routes", label: "Accept Routes Enabled" },
@@ -44,7 +43,7 @@ export const hydrateCreate = async (ctx) => {
         return "complete";
     const device = await ctx.tailscale.devices.getByHostname(router.appName);
     if (!device)
-        return "await_device";
+        return "approve_routes";
     ctx.device = device;
     const routes = await ctx.tailscale.routes.get(device.id);
     if (!routes || routes.unapproved.length > 0)
@@ -70,15 +69,7 @@ export const createTransition = async (phase, ctx) => {
             return Result.ok("deploy_router");
         }
         case "deploy_router": {
-            const authKey = await ctx.tailscale.auth.createKey({
-                reusable: false,
-                ephemeral: false,
-                preauthorized: true,
-                tags: [ctx.tag],
-            });
-            ctx.out.ok("Auth Key Created");
-            await ctx.out.spin("Setting Secrets", () => ctx.fly.secrets.set(ctx.appName, {
-                [SECRET_TAILSCALE_AUTHKEY]: authKey,
+            await ctx.out.spin("Staging Secrets", () => ctx.fly.secrets.set(ctx.appName, {
                 [SECRET_NETWORK_NAME]: ctx.network,
                 [SECRET_ROUTER_ID]: ctx.routerId,
             }, { stage: true }));
@@ -102,34 +93,84 @@ export const createTransition = async (phase, ctx) => {
             const m = machines.find((m) => m.private_ip);
             if (m?.private_ip)
                 ctx.subnet = extractSubnet(m.private_ip);
-            if (!ctx.shouldApprove)
-                return Result.ok("complete");
-            return Result.ok("await_device");
+            return Result.ok("approve_routes");
         }
-        case "await_device": {
-            ctx.device = await waitForDevice(ctx.tailscale, ctx.appName, 180000);
-            ctx.out.ok(`Router Joined Tailnet: ${ctx.device.addresses[0]}`);
+        case "approve_routes": {
             if (!ctx.subnet) {
                 const machines = await ctx.fly.machines.list(ctx.appName);
                 const m = machines.find((m) => m.private_ip);
                 if (m?.private_ip)
                     ctx.subnet = extractSubnet(m.private_ip);
             }
-            return Result.ok("approve_routes");
-        }
-        case "approve_routes": {
-            if (!ctx.device || !ctx.subnet) {
-                return Result.err("Missing Device or Subnet");
-            }
-            const policy = await ctx.tailscale.acl.getPolicy();
+            if (!ctx.subnet)
+                return Result.err("Missing Subnet");
+            let policy = await ctx.tailscale.acl.getPolicy();
             const hasAutoApprover = isAutoApproverConfigured(policy, ctx.tag);
-            if (hasAutoApprover) {
-                ctx.out.ok("Routes Auto-Approved via ACL Policy");
+            let approverReady = hasAutoApprover;
+            if (!hasAutoApprover && !ctx.manual && policy) {
+                const before = policy;
+                policy = patchAutoApprover(policy, ctx.tag, ctx.subnet);
+                assertAdditivePatch(before, policy);
+                const vr = await ctx.tailscale.acl.validatePolicy(policy);
+                if (!vr.ok) {
+                    ctx.out.warn(`Could Not Validate autoApprover Patch: ${vr.error ?? `HTTP ${vr.status}`}`);
+                }
+                else {
+                    const sr = await ctx.tailscale.acl.setPolicy(policy);
+                    if (sr.ok) {
+                        ctx.out.ok(`Added autoApprover for ${ctx.tag} → ${ctx.subnet}`);
+                        approverReady = true;
+                    }
+                    else if (sr.status === 403) {
+                        ctx.out.warn("API Token Lacks ACL Write Permission — Will Approve Routes Manually");
+                    }
+                    else {
+                        ctx.out.warn(`Could Not Set autoApprover: ${sr.error ?? `HTTP ${sr.status}`}`);
+                    }
+                }
             }
-            else {
+            // If the device isn't in the tailnet yet, the router hasn't
+            // authenticated. Mint an auth key and deliver it — the non-staged
+            // secrets set triggers a Fly restart. The router boots with the key,
+            // authenticates, and advertises routes. With autoApprover in place,
+            // routes are auto-approved immediately.
+            if (!ctx.device) {
+                const existing = await ctx.tailscale.devices.getByHostname(ctx.appName);
+                if (existing) {
+                    ctx.device = existing;
+                }
+                else {
+                    const authKey = await ctx.tailscale.auth.createKey({
+                        reusable: false,
+                        ephemeral: false,
+                        preauthorized: true,
+                        tags: [ctx.tag],
+                    });
+                    ctx.out.ok("Auth Key Created");
+                    const keySpinner = ctx.out.spinner("Delivering Auth Key (restarting router)");
+                    await ctx.fly.secrets.set(ctx.appName, {
+                        [SECRET_TAILSCALE_AUTHKEY]: authKey,
+                    });
+                    keySpinner.success("Auth Key Delivered");
+                    if (!ctx.shouldApprove) {
+                        ctx.out.dim("  Skipping Route Approval (--no-auto-approve)");
+                        return Result.ok("complete");
+                    }
+                    ctx.device = await waitForDevice(ctx.tailscale, ctx.appName, 180000);
+                    ctx.out.ok(`Router Joined Tailnet: ${ctx.device.addresses[0]}`);
+                }
+            }
+            const routes = await ctx.tailscale.routes.get(ctx.device.id);
+            if (routes && routes.unapproved.length > 0) {
+                if (approverReady) {
+                    ctx.out.warn("Routes Not Auto-Approved Despite autoApprover — Approving Manually");
+                }
                 await ctx.tailscale.routes.approve(ctx.device.id, [ctx.subnet]);
                 ctx.out.ok("Subnet Routes Approved");
             }
+            else {
+                ctx.out.ok("Routes Auto-Approved via ACL Policy");
+            }
             return Result.ok("configure_dns");
         }
         case "configure_dns": {

package/esm/cli/commands/deploy/index.js

@@ -7,7 +7,7 @@ import { checkArgs } from "../../../lib/args.js";
 import { createOutput } from "../../../lib/output.js";
 import { runMachine } from "../../../lib/machine.js";
 import { registerCommand } from "../../mod.js";
-import { createFlyProvider, } from "../../../providers/fly.js";
+import { createFlyProvider } from "../../../providers/fly.js";
 import { getWorkloadAppName } from "../../../util/naming.js";
 import { findRouterApp, getRouterMachineInfo } from "../../../util/discovery.js";
 import { resolveOrg } from "../../../util/resolve.js";
@@ -126,9 +126,7 @@ const stageSummary = (out, ctx, deployConfig) => {
     }
     out.blank()
         .header("=".repeat(50))
-        .header(hasIssues
-        ? "  Deploy Completed (with Warnings)"
-        : "  Deploy Completed!")
+        .header(hasIssues ? "  Deploy Completed (with Warnings)" : "  Deploy Completed!")
         .header("=".repeat(50))
         .blank()
         .text(`App '${ctx.app}' Is Reachable from Your Tailnet as:`)

package/esm/cli/commands/deploy/machine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/deploy/machine.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/C,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,OAAO,GACP,UAAU,CAAC;AAMf,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE;QACL,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;QACtB,mBAAmB,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,SAAS,EAAE;QACT,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,WAAW,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,iBAAiB,CAAC;IACjC,KAAK,CAAC,EAAE;QACN,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;QACtB,mBAAmB,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAaD,eAAO,MAAM,mBAAmB,GAC9B,KAAK,MAAM,CAAC,YAAY,CAAC,EACzB,YAAY,WAAW,SAMxB,CAAC;AAMF,eAAO,MAAM,aAAa,GACxB,KAAK,SAAS,KACb,OAAO,CAAC,WAAW,CAMrB,CAAC;AAMF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,WAAW,EAClB,KAAK,SAAS,KACb,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CA2G7B,CAAC"}
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/deploy/machine.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/C,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,OAAO,GACP,UAAU,CAAC;AAMf,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE;QACL,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;QACtB,mBAAmB,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,SAAS,EAAE;QACT,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,WAAW,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,iBAAiB,CAAC;IACjC,KAAK,CAAC,EAAE;QACN,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;QACtB,mBAAmB,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAaD,eAAO,MAAM,mBAAmB,GAC9B,KAAK,MAAM,CAAC,YAAY,CAAC,EACzB,YAAY,WAAW,SAMxB,CAAC;AAMF,eAAO,MAAM,aAAa,GACxB,KAAK,SAAS,KACb,OAAO,CAAC,WAAW,CAMrB,CAAC;AAMF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,WAAW,EAClB,KAAK,SAAS,KACb,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CA6G7B,CAAC"}

package/esm/cli/commands/destroy/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/destroy/app.ts"],"names":[],"mappings":"AAiLA,eAAO,MAAM,UAAU,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAoF7D,CAAC"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/destroy/app.ts"],"names":[],"mappings":"AAkLA,eAAO,MAAM,UAAU,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAoF7D,CAAC"}

package/esm/cli/commands/destroy/index.js

@@ -23,10 +23,12 @@ ${bold("SUBCOMMANDS")}
   app        Destroy a workload app on a network
 
 ${bold("OPTIONS")}
+  --manual   Skip automatic Tailscale ACL cleanup (network subcommand)
   --help     Show help for a subcommand
 
 ${bold("EXAMPLES")}
   ambit destroy network browsers
+  ambit destroy network browsers --yes
   ambit destroy app my-app.browsers
   ambit destroy app my-app --network browsers
 

package/esm/cli/commands/destroy/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/destroy/network.ts"],"names":[],"mappings":"AAwQA,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAkDjE,CAAC"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/destroy/network.ts"],"names":[],"mappings":"AAuVA,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CA0DjE,CAAC"}

package/esm/cli/commands/destroy/network.js

@@ -7,7 +7,9 @@ import { checkArgs } from "../../../lib/args.js";
 import { createOutput } from "../../../lib/output.js";
 import { Result } from "../../../lib/result.js";
 import { runMachine } from "../../../lib/machine.js";
-import { findRouterApp, listWorkloadAppsOnNetwork, } from "../../../util/discovery.js";
+import { findRouterApp, listWorkloadAppsOnNetwork } from "../../../util/discovery.js";
+import { getRouterTag } from "../../../util/naming.js";
+import { isAutoApproverConfigured, isTagOwnerConfigured, unpatchAutoApprover, unpatchTagOwner, } from "../../../util/tailscale-local.js";
 import { initSession } from "../../../util/session.js";
 // =============================================================================
 // Phase Labels
@@ -17,6 +19,7 @@ const DESTROY_NETWORK_PHASES = [
     { phase: "clear_dns", label: "Split DNS Cleared" },
     { phase: "remove_device", label: "Tailscale Device Removed" },
     { phase: "delete_app", label: "Fly App Destroyed" },
+    { phase: "clean_acl", label: "ACL Policy Cleaned" },
 ];
 const reportSkipped = (out, startPhase) => {
     for (const { phase, label } of DESTROY_NETWORK_PHASES) {
@@ -107,6 +110,48 @@ const destroyNetworkTransition = async (phase, ctx) => {
             else {
                 ctx.out.skip("Fly App Already Destroyed");
             }
+            return Result.ok(ctx.manual ? "complete" : "clean_acl");
+        }
+        case "clean_acl": {
+            const tag = ctx.tag || getRouterTag(ctx.network);
+            let policy = await ctx.tailscale.acl.getPolicy();
+            if (!policy) {
+                ctx.out.skip("Could Not Read ACL Policy");
+                return Result.ok("complete");
+            }
+            let changed = false;
+            if (isTagOwnerConfigured(policy, tag)) {
+                policy = unpatchTagOwner(policy, tag);
+                changed = true;
+            }
+            if (isAutoApproverConfigured(policy, tag)) {
+                policy = unpatchAutoApprover(policy, tag);
+                changed = true;
+            }
+            if (changed) {
+                const validateResult = await ctx.tailscale.acl
+                    .validatePolicy(policy);
+                if (!validateResult.ok) {
+                    ctx.out.warn(`ACL Policy Validation Failed — Skipping Cleanup: ${validateResult.error ?? `HTTP ${validateResult.status}`}`);
+                    return Result.ok("complete");
+                }
+                const spinner = ctx.out.spinner(`Removing ${tag} from ACL policy`);
+                const result = await ctx.tailscale.acl.setPolicy(policy);
+                if (!result.ok) {
+                    spinner.fail(`Removing ${tag} from ACL policy`);
+                    if (result.status === 403) {
+                        ctx.out.warn("Your API Token Lacks ACL Write Permission. Re-run with --manual to Skip ACL Changes");
+                    }
+                    else {
+                        ctx.out.warn(`Failed to Update ACL Policy: ${result.error ?? `HTTP ${result.status}`}`);
+                    }
+                    return Result.ok("complete");
+                }
+                spinner.success(`Removed ${tag} from ACL policy`);
+            }
+            else {
+                ctx.out.skip(`No ACL Entries Found for ${tag}`);
+            }
             return Result.ok("complete");
         }
         default:
@@ -147,7 +192,14 @@ const stageSummary = (out, ctx) => {
         workloadAppsWarned: 0,
     });
     out.ok("Router Destroyed");
-    if (ctx.tag) {
+    const tag = ctx.tag || getRouterTag(ctx.network);
+    if (!ctx.manual) {
+        out.blank()
+            .dim("If You Added ACL Rules Referencing This Router, Remember to Remove:")
+            .dim(`  acls: rules referencing ${tag}`)
+            .blank();
+    }
+    else if (ctx.tag) {
         out.blank()
             .dim("If You Added ACL Policy Entries for This Router, Remember to Remove:")
             .dim(`  tagOwners:     ${ctx.tag}`)
@@ -169,7 +221,7 @@ const stageSummary = (out, ctx) => {
 export const destroyNetwork = async (argv) => {
     const opts = {
         string: ["network", "org"],
-        boolean: ["help", "yes", "json"],
+        boolean: ["help", "yes", "json", "manual"],
         alias: { y: "yes" },
     };
     const args = parseArgs(argv, opts);
@@ -183,17 +235,25 @@ ${bold("USAGE")}
 
 ${bold("OPTIONS")}
   --org <org>        Fly.io organization slug
+  --manual           Skip automatic Tailscale ACL cleanup (tagOwners + autoApprovers)
   -y, --yes          Skip confirmation prompts
   --json             Output as JSON
 
+${bold("DESCRIPTION")}
+  By default, ambit removes the router's tag from your Tailscale ACL
+  policy (tagOwners and autoApprovers). Use --manual if your API token
+  lacks ACL write permission or you prefer to manage the policy yourself.
+
 ${bold("EXAMPLES")}
   ambit destroy network browsers
-  ambit destroy network browsers --org my-org --yes
+  ambit destroy network browsers --yes
+  ambit destroy network browsers --manual --org my-org
 `);
         return;
     }
     const out = createOutput(args.json);
-    const network = (typeof args._[0] === "string" ? args._[0] : undefined) || args.network;
+    const network = (typeof args._[0] === "string" ? args._[0] : undefined) ||
+        args.network;
     if (!network) {
         return out.die("Network Name Required. Usage: ambit destroy network <name>");
     }
@@ -206,5 +266,6 @@ ${bold("EXAMPLES")}
         org,
         yes: args.yes,
         json: args.json,
+        manual: !!args.manual,
     });
 };