@getcirrus/pds 0.6.0 → 0.7.0

package/README.md

@@ -8,9 +8,9 @@ Cirrus is a single-user [AT Protocol](https://atproto.com) Personal Data Server
 
 Host your own Bluesky identity with minimal infrastructure.
 
-> **⚠️ Experimental Software**
+> **⚠️ Beta Software**
 >
-> This is an early-stage project under active development. **Do not migrate your main Bluesky account to this PDS yet.** Use a test account or create a new identity for experimentation. Data loss, breaking changes, and missing features are expected.
+> This is under active development. Account migration has been tested and works, but breaking changes may still occur. Consider backing up important data before migrating a primary account.
 
 ## What is a PDS?
 
@@ -89,8 +89,7 @@ The package includes a CLI for setup, migration, and secret management.
 Interactive setup wizard for configuring the PDS.
 
 ```bash
-pds init                 # Configure for local development
-pds init --production    # Deploy secrets to Cloudflare
+pds init                 # Configure the PDS (prompts for Cloudflare deploy)
 ```
 
 **What it does:**
@@ -129,6 +128,26 @@ The migration is resumable. If interrupted, run `pds migrate` again to continue.
 - `--dev` – Target the local development server instead of production
 - `--clean` – Delete any existing imported data and start fresh (only works on deactivated accounts)
 
+### `pds identity`
+
+Updates your DID document to point to your new PDS. This is the critical step that tells the network where to find you.
+
+```bash
+pds identity             # Update identity for production
+pds identity --dev       # Update identity for local dev
+pds identity --token XXX # Skip email step if you have a token
+```
+
+The command:
+
+1. Resolves your current DID to find the source PDS
+2. Authenticates with your source PDS (requires your password)
+3. Requests an email confirmation token
+4. Gets the source PDS to sign a PLC operation with the new endpoint
+5. Submits the signed operation to the PLC directory
+
+**Note:** Only `did:plc` identities are supported. `did:web` identities don't use PLC operations.
+
 ### `pds activate`
 
 Enables writes on the account after migration.
@@ -401,10 +420,10 @@ See the [@getcirrus/oauth-provider](../oauth-provider/) package for implementati
 
 1. **Enable R2** in your [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/r2/overview). The bucket will be created automatically on first deploy.
 
-2. **Run the production setup** to deploy secrets:
+2. **Run the setup wizard** and answer "Yes" when asked if you want to deploy to Cloudflare:
 
 ```bash
-npx pds init --production
+npx pds init
 ```
 
 3. **Deploy your worker:**
@@ -419,30 +438,84 @@ wrangler deploy
 
 Moving an existing Bluesky account to your own PDS:
 
-### 1. Configure for migration
+### Step 1: Configure for migration
 
 ```bash
 npx pds init
 # Answer "Yes" when asked about migrating an existing account
 ```
 
-### 2. Deploy and migrate data
+This detects your existing account, generates new signing keys, and configures the PDS in deactivated mode (ready for data import).
+
+### Step 2: Deploy and transfer data
 
 ```bash
 wrangler deploy
 npx pds migrate
 ```
 
-### 3. Update your identity
+The migrate command:
+- Resolves your DID to find the current PDS
+- Authenticates with your source PDS
+- Downloads the repository (posts, follows, likes, etc.)
+- Transfers all blobs (images, videos)
+- Copies user preferences
+
+If interrupted, run `pds migrate` again to resume.
+
+### Step 3: Update your identity
+
+```bash
+npx pds identity
+```
+
+This updates your DID document to point to your new PDS. The command:
+1. Authenticates with your source PDS (requires password)
+2. Requests an email confirmation token
+3. Gets the source PDS to sign a PLC operation with your new endpoint
+4. Submits the signed operation to the PLC directory
 
-Follow the [AT Protocol account migration guide](https://atproto.com/guides/account-migration) to update your DID document. This typically requires email verification from your current PDS.
+You'll receive an email with a confirmation token – enter it when prompted.
 
-### 4. Go live
+### Step 4: Activate the account
 
 ```bash
 npx pds activate
 ```
 
+This enables writes on your new PDS. Your account is now live.
+
+### Step 5: Verify the migration
+
+```bash
+npx pds status
+```
+
+Check that:
+- The account is active
+- The repository has the expected number of records
+- Your handle resolves correctly
+
+### Full command sequence
+
+```bash
+# 1. Configure (answer "Yes" to deploy secrets to Cloudflare)
+npx pds init                    # Configure for migration + deploy secrets
+
+# 2. Deploy and migrate
+wrangler deploy                 # Deploy the worker
+npx pds migrate                 # Transfer data from source PDS
+
+# 3. Update identity
+npx pds identity                # Update DID document (requires email)
+
+# 4. Go live
+npx pds activate                # Enable writes
+
+# 5. Verify
+npx pds status                  # Check everything is working
+```
+
 ## Validation
 
 Records are validated against AT Protocol lexicon schemas before being stored. The PDS uses optimistic validation:

package/dist/cli.js

@@ -7,12 +7,13 @@ import bcrypt from "bcryptjs";
 import { spawn } from "node:child_process";
 import { experimental_patchConfig, experimental_readRawConfig } from "wrangler";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import pc from "picocolors";
 import QRCode from "qrcode";
 import { Client, ClientResponseError, ok } from "@atcute/client";
 import "@atcute/bluesky";
 import "@atcute/atproto";
+import { writeFile } from "node:fs/promises";
 import { CompositeDidDocumentResolver, DohJsonHandleResolver, PlcDidDocumentResolver, WebDidDocumentResolver } from "@atcute/identity-resolver";
 import { getPdsEndpoint } from "@atcute/identity";
 
@@ -21,6 +22,62 @@ import { getPdsEndpoint } from "@atcute/identity";
 * Wrangler integration utilities for setting vars and secrets
 */
 /**
+* Run a wrangler command and capture output.
+* This is the single point of entry for all wrangler CLI invocations.
+*
+* @example
+* // Basic command
+* const { stdout } = await runWrangler(["whoami"]);
+*
+* @example
+* // Command with stdin (for secrets)
+* await runWrangler(["secret", "put", "MY_SECRET"], { stdin: secretValue, throwOnError: true });
+*
+* @example
+* // Command that should throw on failure
+* await runWrangler(["types"], { throwOnError: true });
+*/
+function runWrangler(args, options = {}) {
+	const { stdin, throwOnError = false } = options;
+	return new Promise((resolve$1, reject) => {
+		const child = spawn("wrangler", args, { stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		] });
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (data) => {
+			stdout += data.toString();
+		});
+		child.stderr?.on("data", (data) => {
+			stderr += data.toString();
+		});
+		if (stdin !== void 0) {
+			child.stdin.write(stdin);
+			child.stdin.end();
+		}
+		child.on("close", (code) => {
+			if (throwOnError && code !== 0) {
+				const cmd = `wrangler ${args.join(" ")}`;
+				reject(/* @__PURE__ */ new Error(`${cmd} failed with code ${code}\n${stderr}`));
+			} else resolve$1({
+				stdout,
+				stderr,
+				code
+			});
+		});
+		child.on("error", (err) => {
+			if (throwOnError) reject(err);
+			else resolve$1({
+				stdout,
+				stderr,
+				code: null
+			});
+		});
+	});
+}
+/**
 * Set a var in wrangler.jsonc using experimental_patchConfig
 */
 function setVar(name, value) {
@@ -62,23 +119,13 @@ function setWorkerName(name) {
 * Set a secret using wrangler secret put
 */
 async function setSecret(name, value) {
-	return new Promise((resolve$1, reject) => {
-		const child = spawn("wrangler", [
-			"secret",
-			"put",
-			name
-		], { stdio: [
-			"pipe",
-			"inherit",
-			"inherit"
-		] });
-		child.stdin.write(value);
-		child.stdin.end();
-		child.on("close", (code) => {
-			if (code === 0) resolve$1();
-			else reject(/* @__PURE__ */ new Error(`wrangler secret put ${name} failed with code ${code}`));
-		});
-		child.on("error", reject);
+	await runWrangler([
+		"secret",
+		"put",
+		name
+	], {
+		stdin: value,
+		throwOnError: true
 	});
 }
 /**
@@ -113,7 +160,7 @@ function setCustomDomains(domains) {
 */
 async function detectCloudflareAccounts() {
 	if (getAccountId()) return null;
-	const { stdout, stderr } = await runWranglerWithOutput(["whoami"]);
+	const { stdout, stderr } = await runWrangler(["whoami"]);
 	const output = stdout + stderr;
 	const accounts = [];
 	const regex = /│\s*([^│]+?)\s*│\s*([a-f0-9]{32})\s*│/g;
@@ -129,36 +176,32 @@ async function detectCloudflareAccounts() {
 	return accounts.length > 1 ? accounts : null;
 }
 /**
-* Run a wrangler command and capture output
+* Parse wrangler secret list output (JSON or table format)
+* Exported for testing
 */
-function runWranglerWithOutput(args) {
-	return new Promise((resolve$1) => {
-		const child = spawn("wrangler", args, { stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		] });
-		let stdout = "";
-		let stderr = "";
-		child.stdout?.on("data", (data) => {
-			stdout += data.toString();
-		});
-		child.stderr?.on("data", (data) => {
-			stderr += data.toString();
-		});
-		child.on("close", () => {
-			resolve$1({
-				stdout,
-				stderr
-			});
-		});
-		child.on("error", () => {
-			resolve$1({
-				stdout,
-				stderr
-			});
-		});
-	});
+function parseSecretListOutput(output) {
+	try {
+		const secrets = JSON.parse(output);
+		if (Array.isArray(secrets)) return secrets.map((s) => s.name);
+	} catch {
+		const names = [];
+		const regex = /│\s*(\w+)\s*│\s*secret_text\s*│/g;
+		let match;
+		while ((match = regex.exec(output)) !== null) {
+			const name = match[1];
+			if (name && name !== "Name") names.push(name);
+		}
+		return names;
+	}
+	return [];
+}
+/**
+* List secret names currently deployed to Cloudflare
+* (Values cannot be retrieved - only names)
+*/
+async function listSecrets() {
+	const { stdout } = await runWrangler(["secret", "list"]);
+	return parseSecretListOutput(stdout);
 }
 
 //#endregion
@@ -431,7 +474,7 @@ const secretCommand = defineCommand({
 /**
 * Create a fetch handler that adds optional auth token
 */
-function createAuthHandler(baseUrl, token) {
+function createAuthHandler$1(baseUrl, token) {
 	return async (pathname, init) => {
 		const url = new URL(pathname, baseUrl);
 		const headers = new Headers(init.headers);
@@ -448,14 +491,14 @@ var PDSClient = class PDSClient {
 	constructor(baseUrl, authToken) {
 		this.baseUrl = baseUrl;
 		this.authToken = authToken;
-		this.client = new Client({ handler: createAuthHandler(baseUrl, authToken) });
+		this.client = new Client({ handler: createAuthHandler$1(baseUrl, authToken) });
 	}
 	/**
 	* Set the auth token for subsequent requests
 	*/
 	setAuthToken(token) {
 		this.authToken = token;
-		this.client = new Client({ handler: createAuthHandler(this.baseUrl, token) });
+		this.client = new Client({ handler: createAuthHandler$1(this.baseUrl, token) });
 	}
 	/**
 	* Create a session with identifier and password
@@ -1054,6 +1097,151 @@ function formatCommand(pm, ...args) {
 	if (pm === "npm" || args[0] === "deploy") return `${pm} run ${args.join(" ")}`;
 	return `${pm} ${args.join(" ")}`;
 }
+/**
+* Copy text to clipboard using platform-specific command
+* Falls back gracefully if clipboard is unavailable
+*/
+async function copyToClipboard(text) {
+	const platform = process.platform;
+	let cmd;
+	let args;
+	if (platform === "darwin") {
+		cmd = "pbcopy";
+		args = [];
+	} else if (platform === "linux") {
+		cmd = "xclip";
+		args = ["-selection", "clipboard"];
+	} else if (platform === "win32") {
+		cmd = "clip";
+		args = [];
+	} else return false;
+	return new Promise((resolve$1) => {
+		const child = spawn(cmd, args, { stdio: [
+			"pipe",
+			"ignore",
+			"ignore"
+		] });
+		child.on("error", () => resolve$1(false));
+		child.on("close", (code) => resolve$1(code === 0));
+		child.stdin?.write(text);
+		child.stdin?.end();
+	});
+}
+/**
+* Check if 1Password CLI (op) is available
+* Only checks on POSIX systems (macOS, Linux)
+*/
+async function is1PasswordAvailable() {
+	if (process.platform === "win32") return false;
+	return new Promise((resolve$1) => {
+		const child = spawn("which", ["op"], { stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		] });
+		child.on("error", () => resolve$1(false));
+		child.on("close", (code) => resolve$1(code === 0));
+	});
+}
+/**
+* Save a key to 1Password using the CLI
+* Creates a secure note with the signing key
+*/
+async function saveTo1Password(key, handle) {
+	const itemName = `Cirrus PDS Signing Key - ${handle}`;
+	return new Promise((resolve$1) => {
+		const child = spawn("op", [
+			"item",
+			"create",
+			"--category",
+			"Secure Note",
+			"--title",
+			itemName,
+			`notesPlain=CIRRUS PDS SIGNING KEY\n\nHandle: ${handle}\nCreated: ${(/* @__PURE__ */ new Date()).toISOString()}\n\nWARNING: This key controls your identity!\n\nSIGNING KEY:\n${key}`,
+			"--tags",
+			"cirrus,pds,signing-key"
+		], { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		let stderr = "";
+		child.stderr?.on("data", (data) => {
+			stderr += data.toString();
+		});
+		child.on("error", (err) => {
+			resolve$1({
+				success: false,
+				error: err.message
+			});
+		});
+		child.on("close", (code) => {
+			if (code === 0) resolve$1({
+				success: true,
+				itemName
+			});
+			else resolve$1({
+				success: false,
+				error: stderr || `1Password CLI exited with code ${code}`
+			});
+		});
+	});
+}
+/**
+* Run a shell command and return a promise.
+* Captures output and throws on non-zero exit code.
+* Use this for running npm/pnpm/yarn scripts etc.
+*/
+function runCommand(cmd, args) {
+	return new Promise((resolve$1, reject) => {
+		const child = spawn(cmd, args, { stdio: "pipe" });
+		let output = "";
+		child.stdout?.on("data", (data) => {
+			output += data.toString();
+		});
+		child.stderr?.on("data", (data) => {
+			output += data.toString();
+		});
+		child.on("close", (code) => {
+			if (code === 0) resolve$1();
+			else {
+				if (output) console.error(output);
+				reject(/* @__PURE__ */ new Error(`${cmd} ${args.join(" ")} failed with code ${code}`));
+			}
+		});
+		child.on("error", reject);
+	});
+}
+/**
+* Save a key backup file with appropriate warnings
+*/
+async function saveKeyBackup(key, handle) {
+	const filename = `signing-key-backup-${handle.replace(/[^a-z0-9]/gi, "-")}.txt`;
+	const filepath = join(process.cwd(), filename);
+	await writeFile(filepath, [
+		"=".repeat(60),
+		"CIRRUS PDS SIGNING KEY BACKUP",
+		"=".repeat(60),
+		"",
+		`Handle: ${handle}`,
+		`Created: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+		"",
+		"WARNING: This key controls your identity!",
+		"- Store this file in a secure location (password manager, encrypted drive)",
+		"- Delete this file from your local disk after backing up",
+		"- Never share this key with anyone",
+		"- If compromised, your identity can be stolen",
+		"",
+		"=".repeat(60),
+		"SIGNING KEY (hex-encoded secp256k1 private key)",
+		"=".repeat(60),
+		"",
+		key,
+		"",
+		"=".repeat(60)
+	].join("\n"), { mode: 384 });
+	return filepath;
+}
 
 //#endregion
 //#region src/cli/commands/passkey/add.ts
@@ -1431,7 +1619,7 @@ async function resolveHandleToDid(handle) {
 * Uses @atcute/identity-resolver which is already Workers-compatible
 * (uses redirect: "manual" internally).
 */
-const PLC_DIRECTORY = "https://plc.directory";
+const PLC_DIRECTORY$1 = "https://plc.directory";
 const TIMEOUT_MS = 3e3;
 /**
 * Wrapper that always uses globalThis.fetch so it can be mocked in tests.
@@ -1448,7 +1636,7 @@ var DidResolver = class {
 		this.cache = opts.didCache;
 		this.resolver = new CompositeDidDocumentResolver({ methods: {
 			plc: new PlcDidDocumentResolver({
-				apiUrl: opts.plcUrl ?? PLC_DIRECTORY,
+				apiUrl: opts.plcUrl ?? PLC_DIRECTORY$1,
 				fetch: stubbableFetch
 			}),
 			web: new WebDidDocumentResolver({ fetch: stubbableFetch })
@@ -1535,29 +1723,6 @@ async function ensureAccountConfigured() {
 	const selectedName = accounts.find((a) => a.id === selectedId)?.name;
 	p.log.success(`Account "${selectedName}" saved to wrangler.jsonc`);
 }
-/**
-* Run wrangler types to regenerate TypeScript types
-*/
-function runWranglerTypes() {
-	return new Promise((resolve$1, reject) => {
-		const child = spawn("wrangler", ["types"], { stdio: "pipe" });
-		let output = "";
-		child.stdout?.on("data", (data) => {
-			output += data.toString();
-		});
-		child.stderr?.on("data", (data) => {
-			output += data.toString();
-		});
-		child.on("close", (code) => {
-			if (code === 0) resolve$1();
-			else {
-				if (output) console.error(output);
-				reject(/* @__PURE__ */ new Error(`wrangler types failed with code ${code}`));
-			}
-		});
-		child.on("error", reject);
-	});
-}
 const initCommand = defineCommand({
 	meta: {
 		name: "init",
@@ -1576,6 +1741,33 @@ const initCommand = defineCommand({
 		p.log.info("Let's set up your new home in the Atmosphere!");
 		const wranglerVars = getVars();
 		const devVars = readDevVars();
+		let cfSecrets = [];
+		try {
+			cfSecrets = await listSecrets();
+		} catch {}
+		if (cfSecrets.includes("SIGNING_KEY") && !devVars.SIGNING_KEY) {
+			p.log.error("⚠️  Signing key exists in Cloudflare but not locally!");
+			p.note([
+				"Your PDS has a signing key deployed to Cloudflare, but you don't have",
+				"a local copy in .dev.vars. This usually happens after cloning to a new",
+				"machine without restoring your key backup.",
+				"",
+				"Cloudflare secrets CANNOT be retrieved once set.",
+				"",
+				"To continue, you need to:",
+				"  1. Restore your signing key from your backup (password manager, etc.)",
+				"  2. Add it to .dev.vars as: SIGNING_KEY=your-key-here",
+				"  3. Run 'pds init' again",
+				"",
+				"If you've lost your key backup, your options are limited:",
+				"  • For did:web: Generate a new key (old signatures become unverifiable)",
+				"  • For did:plc: Use a recovery key if you have one",
+				"",
+				"See: https://github.com/ascorbic/cirrus#key-recovery"
+			].join("\n"), "Key Recovery Required");
+			p.outro("Initialization cancelled.");
+			process.exit(1);
+		}
 		const currentVars = {
 			...devVars,
 			...wranglerVars
@@ -1740,13 +1932,101 @@ const initCommand = defineCommand({
 			spinner.stop("Auth token generated");
 			return token;
 		});
-		const signingKey = await getOrGenerateSecret("SIGNING_KEY", devVars, async () => {
+		let signingKey;
+		let signingKeyIsNew = false;
+		if (devVars.SIGNING_KEY) {
+			p.log.success("Using existing signing key from .dev.vars");
+			signingKey = devVars.SIGNING_KEY;
+		} else {
 			spinner.start("Generating signing keypair...");
 			const { privateKey } = await generateSigningKeypair();
 			spinner.stop("Signing keypair generated");
-			return privateKey;
-		});
+			signingKey = privateKey;
+			signingKeyIsNew = true;
+		}
 		const signingKeyPublic = await derivePublicKey(signingKey);
+		if (signingKeyIsNew) {
+			p.log.warn("⚠️  Your signing key controls your identity!");
+			p.note([
+				"This key signs all your posts and controls your account.",
+				"If you lose it, you lose your identity forever.",
+				"",
+				"Cloudflare secrets CANNOT be retrieved after being set.",
+				"Your only copy will be in .dev.vars (this directory).",
+				"",
+				"We strongly recommend backing it up now."
+			].join("\n"), "Critical: Back Up Your Signing Key");
+			const has1Password = await is1PasswordAvailable();
+			const backupOptions = [];
+			if (has1Password) backupOptions.push({
+				value: "1password",
+				label: "Save to 1Password",
+				hint: "recommended - uses op CLI"
+			});
+			backupOptions.push({
+				value: "copy",
+				label: "Copy to clipboard",
+				hint: "paste into password manager"
+			}, {
+				value: "file",
+				label: "Save to file",
+				hint: "signing-key-backup.txt"
+			}, {
+				value: "show",
+				label: "Display it (I'll copy manually)",
+				hint: "shown in terminal"
+			}, {
+				value: "skip",
+				label: "Skip (I understand the risk)",
+				hint: "not recommended"
+			});
+			const backupChoice = await promptSelect({
+				message: "How would you like to back up your signing key?",
+				options: backupOptions
+			});
+			if (backupChoice === "1password") {
+				spinner.start("Saving to 1Password...");
+				const result = await saveTo1Password(signingKey, handle);
+				if (result.success) {
+					spinner.stop("Saved to 1Password");
+					p.log.success(`Created: "${result.itemName}"`);
+				} else {
+					spinner.stop("Failed to save to 1Password");
+					p.log.error(result.error || "Unknown error");
+					p.log.info("Falling back to displaying the key...");
+					p.note([
+						"SIGNING KEY (keep this secret!):",
+						"",
+						signingKey,
+						"",
+						"Copy this to your password manager now."
+					].join("\n"), "🔑 Your Signing Key");
+				}
+			} else if (backupChoice === "copy") {
+				await copyToClipboard(signingKey);
+				p.log.success("Signing key copied to clipboard");
+				p.log.info("Paste it into your password manager now!");
+			} else if (backupChoice === "file") {
+				const backupPath = await saveKeyBackup(signingKey, handle);
+				p.log.success(`Signing key saved to: ${backupPath}`);
+				p.log.warn("Move this file to a secure location and delete the local copy!");
+			} else if (backupChoice === "show") p.note([
+				"SIGNING KEY (keep this secret!):",
+				"",
+				signingKey,
+				"",
+				"Copy this to your password manager now."
+			].join("\n"), "🔑 Your Signing Key");
+			if (backupChoice !== "skip") {
+				if (!await promptConfirm({
+					message: "Have you saved your signing key securely?",
+					initialValue: true
+				})) {
+					p.log.warn("Please back up your key before continuing!");
+					p.note(signingKey, "🔑 Signing Key");
+				}
+			}
+		}
 		const jwtSecret = await getOrGenerateSecret("JWT_SECRET", devVars, async () => {
 			spinner.start("Generating JWT secret...");
 			const secret = generateJwtSecret();
@@ -1775,13 +2055,13 @@ const initCommand = defineCommand({
 		if (isProduction) spinner.start("Deploying secrets to Cloudflare...");
 		else spinner.start("Writing secrets to .dev.vars...");
 		await setSecretValue("AUTH_TOKEN", authToken, local);
-		await setSecretValue("SIGNING_KEY", signingKey, local);
+		if (signingKeyIsNew) await setSecretValue("SIGNING_KEY", signingKey, local);
 		await setSecretValue("JWT_SECRET", jwtSecret, local);
 		await setSecretValue("PASSWORD_HASH", passwordHash, local);
 		spinner.stop(isProduction ? "Secrets deployed" : "Secrets written to .dev.vars");
 		spinner.start("Generating TypeScript types...");
 		try {
-			await runWranglerTypes();
+			await runWrangler(["types"], { throwOnError: true });
 			spinner.stop("TypeScript types generated");
 		} catch {
 			spinner.stop("Failed to generate types (wrangler types)");
@@ -1793,10 +2073,7 @@ const initCommand = defineCommand({
 			"  Handle: " + handle,
 			"  Public signing key: " + signingKeyPublic.slice(0, 20) + "...",
 			"",
-			isProduction ? "Secrets deployed to Cloudflare ☁️" : "Secrets saved to .dev.vars",
-			"",
-			"Auth token (save this!):",
-			"  " + authToken
+			isProduction ? "Secrets deployed to Cloudflare ☁️" : "Secrets saved to .dev.vars"
 		].join("\n"), "Your New Home 🏠");
 		let deployedSecrets = isProduction;
 		if (!isProduction) {
@@ -1807,28 +2084,59 @@ const initCommand = defineCommand({
 			if (!p.isCancel(deployNow) && deployNow) {
 				spinner.start("Deploying secrets to Cloudflare...");
 				await setSecretValue("AUTH_TOKEN", authToken, false);
-				await setSecretValue("SIGNING_KEY", signingKey, false);
+				if (signingKeyIsNew) await setSecretValue("SIGNING_KEY", signingKey, false);
 				await setSecretValue("JWT_SECRET", jwtSecret, false);
 				await setSecretValue("PASSWORD_HASH", passwordHash, false);
 				spinner.stop("Secrets deployed to Cloudflare");
 				deployedSecrets = true;
 			}
 		}
-		if (isMigrating) p.note([
-			deployedSecrets ? "Deploy your worker and run the migration:" : "Push secrets, deploy, and run the migration:",
-			"",
-			...deployedSecrets ? [] : [`  ${formatCommand(pm, "pds", "init", "--production")}`, ""],
-			`  ${formatCommand(pm, "deploy")}`,
-			`  ${formatCommand(pm, "pds", "migrate")}`,
-			"",
-			"To test locally first:",
-			`  ${formatCommand(pm, "dev")}              # in one terminal`,
-			`  ${formatCommand(pm, "pds", "migrate", "--dev")}  # in another`,
-			"",
-			"Then update your identity and flip the switch! 🦋",
-			"  https://atproto.com/guides/account-migration"
-		].join("\n"), "Next Steps 🧳");
-		if (deployedSecrets) p.outro(`Run '${formatCommand(pm, "deploy")}' to launch your PDS! 🚀`);
+		let deployed = false;
+		if (deployedSecrets) {
+			const deployWorker = await p.confirm({
+				message: "Deploy to Cloudflare now?",
+				initialValue: true
+			});
+			if (!p.isCancel(deployWorker) && deployWorker) {
+				spinner.start("Building and deploying to Cloudflare...");
+				try {
+					await runCommand(pm === "npm" ? "npm" : pm, ["run", "build"]);
+					await runCommand(pm === "npm" ? "npm" : pm, ["run", "deploy"]);
+					spinner.stop("Deployed to Cloudflare! 🚀");
+					deployed = true;
+				} catch (error) {
+					spinner.stop("Deployment failed");
+					p.log.error(`Failed to deploy: ${error instanceof Error ? error.message : "Unknown error"}`);
+					p.log.info(`You can deploy manually with: ${formatCommand(pm, "deploy")}`);
+				}
+			}
+		}
+		if (isMigrating) {
+			const nextSteps = deployed ? [
+				"Run the migration:",
+				"",
+				`  ${formatCommand(pm, "pds", "migrate")}`,
+				"",
+				"Then update your identity and flip the switch! 🦋",
+				"  https://atproto.com/guides/account-migration"
+			] : [
+				deployedSecrets ? "Deploy your worker and run the migration:" : "Push secrets, deploy, and run the migration:",
+				"",
+				...deployedSecrets ? [] : [`  ${formatCommand(pm, "pds", "init", "--production")}`, ""],
+				`  ${formatCommand(pm, "deploy")}`,
+				`  ${formatCommand(pm, "pds", "migrate")}`,
+				"",
+				"To test locally first:",
+				`  ${formatCommand(pm, "dev")}              # in one terminal`,
+				`  ${formatCommand(pm, "pds", "migrate", "--dev")}  # in another`,
+				"",
+				"Then update your identity and flip the switch! 🦋",
+				"  https://atproto.com/guides/account-migration"
+			];
+			p.note(nextSteps.join("\n"), "Next Steps 🧳");
+		}
+		if (deployed) p.outro(`Your PDS is live at https://${hostname}! 🚀`);
+		else if (deployedSecrets) p.outro(`Run '${formatCommand(pm, "deploy")}' to launch your PDS! 🚀`);
 		else p.outro(`Run '${formatCommand(pm, "dev")}' to start your PDS locally! 🦋`);
 	}
 });
@@ -1847,7 +2155,7 @@ async function getOrGenerateSecret(name, devVars, generate) {
 
 //#endregion
 //#region src/cli/commands/migrate.ts
-const brightNote$1 = (lines) => lines.map((l) => `\x1b[0m${l}`).join("\n");
+const brightNote$2 = (lines) => lines.map((l) => `\x1b[0m${l}`).join("\n");
 /**
 * Format number with commas
 */
@@ -1969,7 +2277,7 @@ const migrateCommand = defineCommand({
 				p.outro("Migration cancelled.");
 				process.exit(1);
 			}
-			p.note(brightNote$1([
+			p.note(brightNote$2([
 				pc.bold("This will permanently delete from your new PDS:"),
 				"",
 				`  • ${num(status.repoBlocks)} repository blocks`,
@@ -2045,7 +2353,7 @@ const migrateCommand = defineCommand({
 				`  👥 ${num(profileStats.followsCount)} follows`,
 				`  ...plus all your images, likes and preferences`
 			] : [`  📝 Posts, follows, images, likes and preferences`];
-			p.note(brightNote$1([
+			p.note(brightNote$2([
 				pc.bold(`@${handle}`) + ` (${did.slice(0, 20)}...)`,
 				"",
 				`Currently at:  ${sourceDomain}`,
@@ -2172,12 +2480,12 @@ const migrateCommand = defineCommand({
 	}
 });
 function showNextSteps(pm, sourceDomain) {
-	p.note(brightNote$1([
+	p.note(brightNote$2([
 		pc.bold("Your data is safe in your new PDS."),
 		"Two more steps to go live:",
 		"",
 		pc.bold("1. Update your identity"),
-		"   Tell the network where you live now.",
+		`   ${formatCommand(pm, "pds", "identity")}`,
 		`   (Requires email verification from ${sourceDomain})`,
 		"",
 		pc.bold("2. Flip the switch"),
@@ -2187,6 +2495,394 @@ function showNextSteps(pm, sourceDomain) {
 	]), "Almost there!");
 }
 
+//#endregion
+//#region src/cli/utils/plc-client.ts
+/**
+* PLC Directory client for identity operations
+*
+* Handles communication with the PLC directory and source PDS
+* for DID document updates during migration.
+*
+* Uses @atcute/client for type-safe XRPC calls.
+*/
+const PLC_DIRECTORY = "https://plc.directory";
+/**
+* Create a fetch handler that adds optional auth token
+*/
+function createAuthHandler(baseUrl, token) {
+	return async (pathname, init) => {
+		const url = new URL(pathname, baseUrl);
+		const headers = new Headers(init.headers);
+		if (token) headers.set("Authorization", `Bearer ${token}`);
+		return fetch(url, {
+			...init,
+			headers
+		});
+	};
+}
+/**
+* Client for interacting with source PDS for PLC operations
+*
+* Uses @atcute/client for type-safe XRPC calls to:
+* - com.atproto.identity.requestPlcOperationSignature
+* - com.atproto.identity.signPlcOperation
+*/
+var SourcePdsPlcClient = class {
+	client;
+	authToken;
+	baseUrl;
+	constructor(baseUrl, authToken) {
+		this.baseUrl = baseUrl;
+		this.authToken = authToken;
+		this.client = new Client({ handler: createAuthHandler(baseUrl, authToken) });
+	}
+	setAuthToken(token) {
+		this.authToken = token;
+		this.client = new Client({ handler: createAuthHandler(this.baseUrl, token) });
+	}
+	/**
+	* Request a PLC operation signature from the source PDS.
+	* This triggers the source PDS to send an email token to the user.
+	*
+	* Uses: com.atproto.identity.requestPlcOperationSignature
+	*/
+	async requestPlcOperationSignature() {
+		try {
+			await ok(this.client.post("com.atproto.identity.requestPlcOperationSignature", { as: null }));
+			return {
+				success: true,
+				credentialInfo: { type: "email" }
+			};
+		} catch (err) {
+			return {
+				success: false,
+				error: err instanceof Error ? err.message : "Network error"
+			};
+		}
+	}
+	/**
+	* Get a signed PLC operation from the source PDS.
+	* This builds and signs the operation to migrate to the new PDS.
+	*
+	* Uses: com.atproto.identity.signPlcOperation
+	*
+	* @param token - The email token received from the source PDS
+	* @param newPdsEndpoint - The endpoint URL of the new PDS
+	* @param newSigningKey - The new signing key DID (did:key:...)
+	*/
+	async signPlcOperation(token, newPdsEndpoint, newSigningKey) {
+		try {
+			return {
+				success: true,
+				signedOperation: (await ok(this.client.post("com.atproto.identity.signPlcOperation", { input: {
+					token,
+					rotationKeys: void 0,
+					alsoKnownAs: void 0,
+					verificationMethods: { atproto: newSigningKey },
+					services: { atproto_pds: {
+						type: "AtprotoPersonalDataServer",
+						endpoint: newPdsEndpoint
+					} }
+				} }))).operation
+			};
+		} catch (err) {
+			const errorMessage = err instanceof Error ? err.message : "Network error";
+			if (errorMessage.includes("expired") || errorMessage.includes("ExpiredToken")) return {
+				success: false,
+				error: "Token expired. Request a new one and try again."
+			};
+			if (errorMessage.includes("invalid") || errorMessage.includes("InvalidToken")) return {
+				success: false,
+				error: "Invalid token. Check you entered it correctly."
+			};
+			return {
+				success: false,
+				error: errorMessage
+			};
+		}
+	}
+};
+/**
+* Client for interacting with the PLC directory
+*
+* The PLC directory has its own REST API (not XRPC), so we use raw fetch here.
+* See: https://web.plc.directory/
+*/
+var PlcDirectoryClient = class {
+	constructor(plcUrl = PLC_DIRECTORY) {
+		this.plcUrl = plcUrl;
+	}
+	/**
+	* Get the audit log for a DID (list of all operations)
+	*/
+	async getAuditLog(did) {
+		const res = await fetch(`${this.plcUrl}/${did}/log/audit`);
+		if (!res.ok) throw new Error(`Failed to fetch audit log: ${res.status}`);
+		return res.json();
+	}
+	/**
+	* Get the current DID document
+	*/
+	async getDocument(did) {
+		const res = await fetch(`${this.plcUrl}/${did}`);
+		if (!res.ok) {
+			if (res.status === 404) return null;
+			throw new Error(`Failed to fetch DID document: ${res.status}`);
+		}
+		return res.json();
+	}
+	/**
+	* Submit a signed PLC operation to the directory
+	*/
+	async submitOperation(did, operation) {
+		try {
+			const res = await fetch(`${this.plcUrl}/${did}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(operation)
+			});
+			if (!res.ok) return {
+				success: false,
+				error: `PLC directory rejected operation: ${await res.text()}`
+			};
+			return { success: true };
+		} catch (err) {
+			return {
+				success: false,
+				error: err instanceof Error ? err.message : "Network error"
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/cli/commands/identity.ts
+/**
+* Identity command - update DID document to point to new PDS
+*
+* This command handles the PLC operation flow for migrating identity
+* from source PDS to Cirrus. It:
+* 1. Requests an email token from the source PDS
+* 2. Gets the source PDS to sign a PLC operation with the new endpoint
+* 3. Submits the signed operation to the PLC directory
+*/
+const brightNote$1 = (lines) => lines.map((l) => `\x1b[0m${l}`).join("\n");
+const identityCommand = defineCommand({
+	meta: {
+		name: "identity",
+		description: "Update your DID to point to your new PDS"
+	},
+	args: {
+		dev: {
+			type: "boolean",
+			description: "Target local development server instead of production",
+			default: false
+		},
+		token: {
+			type: "string",
+			description: "Email token (if you already have one)"
+		}
+	},
+	async run({ args }) {
+		const pm = detectPackageManager();
+		const isDev = args.dev;
+		p.intro("🆔 Update Identity");
+		const spinner = p.spinner();
+		const wranglerVars = getVars();
+		const config = {
+			...readDevVars(),
+			...wranglerVars
+		};
+		const did = config.DID;
+		const handle = config.HANDLE;
+		const authToken = config.AUTH_TOKEN;
+		const pdsHostname = config.PDS_HOSTNAME;
+		const signingKey = config.SIGNING_KEY;
+		if (!did) {
+			p.log.error("No DID configured. Run 'pds init' first.");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		if (!handle) {
+			p.log.error("No HANDLE configured. Run 'pds init' first.");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		if (!authToken) {
+			p.log.error("No AUTH_TOKEN found. Run 'pds init' first.");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		if (!pdsHostname && !isDev) {
+			p.log.error("No PDS_HOSTNAME configured in wrangler.jsonc");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		if (!signingKey) {
+			p.log.error("No SIGNING_KEY found. Run 'pds init' first.");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		if (!did.startsWith("did:plc:")) {
+			p.log.error("Only did:plc identities are supported for now.");
+			p.log.info("did:web identities don't use PLC operations.");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		let targetUrl;
+		try {
+			targetUrl = getTargetUrl(isDev, pdsHostname);
+		} catch (err) {
+			p.log.error(err instanceof Error ? err.message : "Configuration error");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		const targetDomain = getDomain(targetUrl);
+		spinner.start("Resolving your DID...");
+		const didDoc = await new DidResolver().resolve(did);
+		if (!didDoc) {
+			spinner.stop("Failed to resolve DID");
+			p.log.error(`Could not resolve DID: ${did}`);
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		const sourcePdsUrl = getPdsEndpoint(didDoc);
+		if (!sourcePdsUrl) {
+			spinner.stop("No PDS found in DID document");
+			p.log.error("Could not find PDS endpoint in DID document");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		const sourceDomain = getDomain(sourcePdsUrl);
+		spinner.stop(`Current PDS: ${sourceDomain}`);
+		const targetEndpoint = targetUrl.replace(/\/$/, "");
+		if (sourcePdsUrl.replace(/\/$/, "") === targetEndpoint) {
+			p.log.success("Your DID already points to your new PDS!");
+			p.log.info(`Next step: ${formatCommand(pm, "pds", "activate")}`);
+			p.outro("All set!");
+			return;
+		}
+		spinner.start(`Checking ${targetDomain}...`);
+		if (!await new PDSClient(targetUrl, authToken).healthCheck()) {
+			spinner.stop(`PDS not responding`);
+			p.log.error(`Your new PDS isn't responding at ${targetUrl}`);
+			if (isDev) p.log.info(`Start it with: ${formatCommand(pm, "dev")}`);
+			else p.log.info(`Make sure your worker is deployed: ${formatCommand(pm, "deploy")}`);
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		spinner.stop(`New PDS is ready`);
+		spinner.start("Preparing signing key...");
+		const signingKeyDid = await getSigningKeyDid(signingKey);
+		if (!signingKeyDid) {
+			spinner.stop("Failed to derive signing key");
+			p.log.error("Could not convert signing key to did:key format");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		spinner.stop("Signing key ready");
+		const sourceDisplayName = sourceDomain.endsWith(".bsky.network") ? "bsky.social" : sourceDomain;
+		p.note(brightNote$1([
+			pc.bold("Updating your identity:"),
+			"",
+			`${pc.dim("From:")} ${sourceDisplayName}`,
+			`${pc.dim("To:")}   ${targetDomain}`,
+			"",
+			pc.dim("This tells the network where to find you.")
+		]), "🔄 DID Update");
+		const sourcePdsClient = new SourcePdsPlcClient(sourcePdsUrl);
+		let token = args.token;
+		if (!token) {
+			const password = await p.password({ message: `Your password for ${sourceDisplayName}:` });
+			if (p.isCancel(password)) {
+				p.cancel("Identity update cancelled.");
+				process.exit(0);
+			}
+			spinner.start(`Logging in to ${sourceDisplayName}...`);
+			const sourceClient = new PDSClient(sourcePdsUrl);
+			try {
+				const session = await sourceClient.createSession(did, password);
+				sourcePdsClient.setAuthToken(session.accessJwt);
+				spinner.stop("Authenticated");
+			} catch (err) {
+				spinner.stop("Login failed");
+				p.log.error(err instanceof Error ? err.message : "Authentication failed");
+				p.outro("Identity update cancelled.");
+				process.exit(1);
+			}
+			spinner.start("Requesting identity update token...");
+			const signatureRequest = await sourcePdsClient.requestPlcOperationSignature();
+			if (!signatureRequest.success) {
+				spinner.stop("Failed to request token");
+				p.log.error(signatureRequest.error ?? "Could not request PLC operation signature");
+				p.outro("Identity update cancelled.");
+				process.exit(1);
+			}
+			spinner.stop("Token requested");
+			p.log.info("");
+			p.log.info(pc.bold("📧 Check your email!"));
+			p.log.info(`${sourceDisplayName} has sent you a confirmation code.`);
+			p.log.info("");
+			token = await promptText({
+				message: "Enter the confirmation code from your email:",
+				placeholder: "XXXXX-XXXXX",
+				validate: (v) => {
+					if (!v || v.trim().length < 5) return "Please enter the confirmation code";
+				}
+			});
+		}
+		spinner.start("Signing identity update...");
+		const signResult = await sourcePdsClient.signPlcOperation(token.trim(), targetUrl, signingKeyDid);
+		if (!signResult.success || !signResult.signedOperation) {
+			spinner.stop("Failed to sign operation");
+			p.log.error(signResult.error ?? "Could not sign PLC operation");
+			if (signResult.error?.includes("expired")) p.log.info("Run the command again to request a new token.");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		spinner.stop("Operation signed");
+		const plcClient = new PlcDirectoryClient();
+		spinner.start("Submitting to PLC directory...");
+		const submitResult = await plcClient.submitOperation(did, signResult.signedOperation);
+		if (!submitResult.success) {
+			spinner.stop("Failed to submit operation");
+			p.log.error(submitResult.error ?? "PLC directory rejected the operation");
+			p.outro("Identity update cancelled.");
+			process.exit(1);
+		}
+		spinner.stop("Identity updated!");
+		spinner.start("Verifying update...");
+		await new Promise((resolve$1) => setTimeout(resolve$1, 1e3));
+		const newDidDoc = await new DidResolver().resolve(did);
+		if ((newDidDoc ? getPdsEndpoint(newDidDoc) : null)?.replace(/\/$/, "") === targetEndpoint) spinner.stop("Verified! DID now points to new PDS");
+		else {
+			spinner.stop("Update submitted (verification pending)");
+			p.log.warn("It may take a moment for the update to propagate.");
+		}
+		p.log.success("Your identity now points to your new PDS!");
+		p.note(brightNote$1([
+			pc.bold("Final step:"),
+			"",
+			`Run: ${formatCommand(pm, "pds", "activate")}`,
+			"",
+			"This enables writes and notifies the network."
+		]), "Almost done!");
+		p.outro("Identity updated! 🎉");
+	}
+});
+/**
+* Convert a hex-encoded secp256k1 private key to a did:key
+*
+* This imports the private key and returns the did:key representation.
+*/
+async function getSigningKeyDid(hexPrivateKey) {
+	try {
+		return (await Secp256k1Keypair.import(hexPrivateKey)).did();
+	} catch {
+		return null;
+	}
+}
+
 //#endregion
 //#region src/cli/utils/checks.ts
 /**
@@ -3028,6 +3724,7 @@ runMain(defineCommand({
 		secret: secretCommand,
 		passkey: passkeyCommand,
 		migrate: migrateCommand,
+		identity: identityCommand,
 		activate: activateCommand,
 		deactivate: deactivateCommand,
 		status: statusCommand,

package/dist/index.js

@@ -3755,7 +3755,7 @@ function renderPasskeyErrorPage(error, description) {
 
 //#endregion
 //#region package.json
-var version = "0.6.0";
+var version = "0.7.0";
 
 //#endregion
 //#region src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getcirrus/pds",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Cirrus – A single-user AT Protocol PDS on Cloudflare Workers",
   "type": "module",
   "main": "dist/index.js",