@warpgogol/werkstatt-shared 0.2.0

package/src/ontology/tests/sternsystem-owner.test.ts

@@ -0,0 +1,63 @@
+import { test, expect, describe } from "vitest";
+import { systemConfigSchema } from "@warpgogol/werkstatt/schemas";
+
+const validBaseEntry = {
+  schemaVersion: "system-config/v1",
+  id: "test-site",
+  cosmicStar: "Vega",
+  mirrors: [{ path: "https://github.com/org/test-site", storageType: "non-bare" }],
+  pinnedPlatform: "1.0.0",
+  status: "active" as const,
+  registeredAt: "2026-07-27T00:00:00Z",
+  notes: "",
+};
+
+describe("systemConfigSchema owner field (RFC-0561)", () => {
+  test("accepts entry without owner (backwards compatible)", () => {
+    const result = systemConfigSchema.parse(validBaseEntry);
+    expect(result.owner).toBeUndefined();
+  });
+
+  test("accepts entry with valid did:web owner", () => {
+    const result = systemConfigSchema.parse({
+      ...validBaseEntry,
+      owner: "did:web:warpgogol.com#operator-v1",
+    });
+    expect(result.owner).toBe("did:web:warpgogol.com#operator-v1");
+  });
+
+  test("rejects entry with non-did:web owner", () => {
+    expect(() =>
+      systemConfigSchema.parse({
+        ...validBaseEntry,
+        owner: "not-a-did",
+      }),
+    ).toThrow();
+  });
+
+  test("rejects entry with empty string owner", () => {
+    expect(() =>
+      systemConfigSchema.parse({
+        ...validBaseEntry,
+        owner: "",
+      }),
+    ).toThrow();
+  });
+
+  test("rejects entry with did:web but no key-version fragment", () => {
+    expect(() =>
+      systemConfigSchema.parse({
+        ...validBaseEntry,
+        owner: "did:web:warpgogol.com",
+      }),
+    ).toThrow();
+  });
+
+  test("accepts entry with did:web owner with subdomain", () => {
+    const result = systemConfigSchema.parse({
+      ...validBaseEntry,
+      owner: "did:web:sub.example.com#key-1",
+    });
+    expect(result.owner).toBe("did:web:sub.example.com#key-1");
+  });
+});

package/src/ontology/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});

package/src/passport/dht-sign.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from "vitest";
+import { dhtEntryBytes, signDhtEntry, verifyDhtEntry, type DHTEntryData } from "./dht-sign.ts";
+import { generateKeypair } from "./sign.ts";
+import type { DHTSiteEntry } from "@warpgogol/werkstatt-shared/ontology/operations";
+
+describe("dht-sign", () => {
+  it("dhtEntryBytes produces deterministic canonical bytes", () => {
+    const entry: DHTEntryData = {
+      siteId: "test-site",
+      owner: "did:web:example.com#v1",
+      workshopEndpoint: "10.0.0.1:7947",
+      mirrors: ["10.0.0.2:7947"],
+      registeredAt: "2025-01-01T00:00:00.000Z",
+      lastUpdated: "2025-01-01T00:00:00.000Z",
+    };
+
+    const bytes1 = dhtEntryBytes(entry);
+    const bytes2 = dhtEntryBytes(entry);
+
+    expect(bytes1).toEqual(bytes2);
+    expect(bytes1.length).toBeGreaterThan(0);
+  });
+
+  it("dhtEntryBytes excludes signature field", () => {
+    const entryData: DHTEntryData = {
+      siteId: "test-site",
+      owner: "did:web:example.com#v1",
+      workshopEndpoint: "10.0.0.1:7947",
+      mirrors: [],
+      registeredAt: "2025-01-01T00:00:00.000Z",
+      lastUpdated: "2025-01-01T00:00:00.000Z",
+    };
+
+    const bytes = dhtEntryBytes(entryData);
+    const decoded = new TextDecoder().decode(bytes);
+    expect(decoded).not.toContain("signature");
+  });
+
+  it("signDhtEntry and verifyDhtEntry round-trip", async () => {
+    const keypair = await generateKeypair();
+    const entryData: DHTEntryData = {
+      siteId: "test-site",
+      owner: "did:web:example.com#v1",
+      workshopEndpoint: "10.0.0.1:7947",
+      mirrors: ["10.0.0.2:7947"],
+      registeredAt: "2025-01-01T00:00:00.000Z",
+      lastUpdated: "2025-01-01T00:00:00.000Z",
+    };
+
+    const signature = await signDhtEntry(entryData, keypair.privateKeyHex);
+    expect(signature).toBeTruthy();
+    expect(signature.length).toBeGreaterThan(0);
+
+    const fullEntry: DHTSiteEntry = { ...entryData, signature };
+    const isValid = await verifyDhtEntry(fullEntry, keypair.publicKeyMultibase);
+    expect(isValid).toBe(true);
+  });
+
+  it("verifyDhtEntry rejects tampered entries", async () => {
+    const keypair = await generateKeypair();
+    const entryData: DHTEntryData = {
+      siteId: "test-site",
+      owner: "did:web:example.com#v1",
+      workshopEndpoint: "10.0.0.1:7947",
+      mirrors: [],
+      registeredAt: "2025-01-01T00:00:00.000Z",
+      lastUpdated: "2025-01-01T00:00:00.000Z",
+    };
+
+    const signature = await signDhtEntry(entryData, keypair.privateKeyHex);
+    const tamperedEntry: DHTSiteEntry = {
+      ...entryData,
+      workshopEndpoint: "10.0.0.99:7947",
+      signature,
+    };
+
+    const isValid = await verifyDhtEntry(tamperedEntry, keypair.publicKeyMultibase);
+    expect(isValid).toBe(false);
+  });
+
+  it("verifyDhtEntry rejects wrong public key", async () => {
+    const keypair1 = await generateKeypair();
+    const keypair2 = await generateKeypair();
+    const entryData: DHTEntryData = {
+      siteId: "test-site",
+      owner: "did:web:example.com#v1",
+      workshopEndpoint: "10.0.0.1:7947",
+      mirrors: [],
+      registeredAt: "2025-01-01T00:00:00.000Z",
+      lastUpdated: "2025-01-01T00:00:00.000Z",
+    };
+
+    const signature = await signDhtEntry(entryData, keypair1.privateKeyHex);
+    const fullEntry: DHTSiteEntry = { ...entryData, signature };
+
+    const isValid = await verifyDhtEntry(fullEntry, keypair2.publicKeyMultibase);
+    expect(isValid).toBe(false);
+  });
+});

package/src/passport/dht-sign.ts

@@ -0,0 +1,73 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0565: DHT entry signing and verification — canonicalization and sign/verify
+wrappers for DHTSiteEntry, built on the existing Ed25519 signBytes/verifyBytes
+primitives from sign.ts. Analogous to identity-sign.ts but for the DHT site
+entry shape.
+</purpose>
+<non-goals>
+  <item>Do not handle key storage or management — private keys arrive as env vars.</item>
+  <item>Do not assemble W3C VC envelopes — DHT entries use a simple signature string, not VCProof.</item>
+  <item>Do not modify sign.ts — this module wraps signBytes/verifyBytes.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0565: initial DHT entry signing module.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * @warpgogol/werkstatt-shared/passport/dht-sign — DHT entry signing (RFC-0565)
+ *
+ * Uses signBytes/verifyBytes from sign.ts with a dedicated canonicalization
+ * function for DHT site entries. The signature field is excluded from
+ * canonicalization (it is computed over the entry data without the signature).
+ */
+
+import { signBytes, verifyBytes } from "./sign.ts";
+import type { DHTSiteEntry } from "@warpgogol/werkstatt-shared/ontology/operations";
+
+/**
+ * DHTSiteEntry without the signature field — the data that is actually signed.
+ */
+export type DHTEntryData = Omit<DHTSiteEntry, "signature">;
+
+/**
+ * Produce canonical UTF-8 bytes from a DHT entry (excluding signature).
+ * DETERMINISM: identical inputs → identical bytes (sorted-key JSON, no whitespace).
+ */
+export function dhtEntryBytes(entry: DHTEntryData): Uint8Array {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(entry).sort()) {
+    sorted[key] = (entry as Record<string, unknown>)[key];
+  }
+  const canonical = JSON.stringify(sorted);
+  return new TextEncoder().encode(canonical);
+}
+
+/**
+ * Sign a DHT entry and return a multibase Ed25519 signature string.
+ *
+ * @param entry          — DHT entry data (without signature)
+ * @param privateKeyHex  — 32-byte Ed25519 private key as hex (from env secret)
+ * @returns multibase base58btc signature string
+ */
+export async function signDhtEntry(entry: DHTEntryData, privateKeyHex: string): Promise<string> {
+  return signBytes(privateKeyHex, dhtEntryBytes(entry));
+}
+
+/**
+ * Verify a DHT entry signature against the published public key.
+ *
+ * @param entry              — full DHT site entry (including signature)
+ * @param publicKeyMultibase — multibase public key from werkstatt.identity.json
+ * @returns true if signature is valid
+ */
+export async function verifyDhtEntry(
+  entry: DHTSiteEntry,
+  publicKeyMultibase: string,
+): Promise<boolean> {
+  const { signature, ...entryData } = entry;
+  return verifyBytes(publicKeyMultibase, dhtEntryBytes(entryData), signature);
+}

package/src/passport/identity-sign.test.ts

@@ -0,0 +1,134 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>RFC-0558: unit tests for identity credential signing and verification.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0558: initial identity-sign tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect } from "vitest";
+import { generateKeypair } from "./sign.ts";
+import {
+  identityCredentialBytes,
+  signIdentityCredential,
+  verifyIdentityCredential,
+} from "./identity-sign.ts";
+import type { SiteOwnershipCredentialSubject, ActorDelegationCredentialSubject } from "./schema.ts";
+
+describe("identityCredentialBytes", () => {
+  it("produces deterministic bytes for SiteOwnershipCredentialSubject", () => {
+    const subject: SiteOwnershipCredentialSubject = {
+      id: "did:web:warpgogol.com#operator-v1",
+      siteId: "warpgogol-com",
+      role: "owner",
+    };
+    const bytes1 = identityCredentialBytes(subject);
+    const bytes2 = identityCredentialBytes(subject);
+    expect(bytes1).toEqual(bytes2);
+  });
+
+  it("produces deterministic bytes for ActorDelegationCredentialSubject", () => {
+    const subject: ActorDelegationCredentialSubject = {
+      id: "did:web:warpgogol.com#agent-v1",
+      siteId: "warpgogol-com",
+      delegatedBy: "did:web:warpgogol.com#operator-v1",
+      expiresAt: "2027-01-01T00:00:00.000Z",
+      scopes: ["*"],
+    };
+    const bytes1 = identityCredentialBytes(subject);
+    const bytes2 = identityCredentialBytes(subject);
+    expect(bytes1).toEqual(bytes2);
+  });
+
+  it("produces different bytes for different subjects", () => {
+    const subject1: SiteOwnershipCredentialSubject = {
+      id: "did:web:warpgogol.com#operator-v1",
+      siteId: "warpgogol-com",
+      role: "owner",
+    };
+    const subject2: SiteOwnershipCredentialSubject = {
+      id: "did:web:warpgogol.com#operator-v2",
+      siteId: "warpgogol-com",
+      role: "owner",
+    };
+    expect(identityCredentialBytes(subject1)).not.toEqual(identityCredentialBytes(subject2));
+  });
+});
+
+describe("signIdentityCredential / verifyIdentityCredential", () => {
+  it("round-trips for SiteOwnershipCredentialSubject", async () => {
+    const keypair = await generateKeypair();
+    const subject: SiteOwnershipCredentialSubject = {
+      id: "did:web:warpgogol.com#operator-v1",
+      siteId: "warpgogol-com",
+      role: "owner",
+    };
+    const proof = await signIdentityCredential(
+      subject,
+      keypair.privateKeyHex,
+      "did:web:warpgogol.com#v1",
+      "2026-07-27T00:00:00.000Z",
+    );
+    const valid = await verifyIdentityCredential(subject, proof, keypair.publicKeyMultibase);
+    expect(valid).toBe(true);
+  });
+
+  it("round-trips for ActorDelegationCredentialSubject", async () => {
+    const keypair = await generateKeypair();
+    const subject: ActorDelegationCredentialSubject = {
+      id: "did:web:warpgogol.com#agent-v1",
+      siteId: "warpgogol-com",
+      delegatedBy: "did:web:warpgogol.com#operator-v1",
+      expiresAt: "2027-01-01T00:00:00.000Z",
+      scopes: ["mission.open", "workpiece.write"],
+    };
+    const proof = await signIdentityCredential(
+      subject,
+      keypair.privateKeyHex,
+      "did:web:warpgogol.com#v1",
+      "2026-07-27T00:00:00.000Z",
+    );
+    const valid = await verifyIdentityCredential(subject, proof, keypair.publicKeyMultibase);
+    expect(valid).toBe(true);
+  });
+
+  it("fails verification for tampered subject", async () => {
+    const keypair = await generateKeypair();
+    const subject: SiteOwnershipCredentialSubject = {
+      id: "did:web:warpgogol.com#operator-v1",
+      siteId: "warpgogol-com",
+      role: "owner",
+    };
+    const proof = await signIdentityCredential(
+      subject,
+      keypair.privateKeyHex,
+      "did:web:warpgogol.com#v1",
+      "2026-07-27T00:00:00.000Z",
+    );
+    const tampered: SiteOwnershipCredentialSubject = {
+      ...subject,
+      siteId: "other-site",
+    };
+    const valid = await verifyIdentityCredential(tampered, proof, keypair.publicKeyMultibase);
+    expect(valid).toBe(false);
+  });
+
+  it("fails verification with wrong public key", async () => {
+    const keypair1 = await generateKeypair();
+    const keypair2 = await generateKeypair();
+    const subject: SiteOwnershipCredentialSubject = {
+      id: "did:web:warpgogol.com#operator-v1",
+      siteId: "warpgogol-com",
+      role: "owner",
+    };
+    const proof = await signIdentityCredential(
+      subject,
+      keypair1.privateKeyHex,
+      "did:web:warpgogol.com#v1",
+      "2026-07-27T00:00:00.000Z",
+    );
+    const valid = await verifyIdentityCredential(subject, proof, keypair2.publicKeyMultibase);
+    expect(valid).toBe(false);
+  });
+});

package/src/passport/identity-sign.ts

@@ -0,0 +1,85 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0558: Identity credential signing and verification — canonicalization and
+sign/verify wrappers for SiteOwnershipCredential and ActorDelegationCredential
+subjects, built on the existing Ed25519 signBytes/verifyBytes primitives.
+</purpose>
+<non-goals>
+  <item>Do not handle key storage or management — private keys arrive as env vars.</item>
+  <item>Do not assemble full W3C VC envelopes — callers attach the proof after signing.</item>
+  <item>Do not modify sign.ts — this module wraps signBytes/verifyBytes, not signCredential.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0558: initial identity credential signing module.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * @warpgogol/werkstatt-shared/passport/identity-sign — Identity credential signing (RFC-0558)
+ *
+ * Uses signBytes/verifyBytes from sign.ts with a dedicated canonicalization
+ * function for identity credential subjects. signCredential is NOT reused —
+ * it is typed to CredentialSubjectDigest (build provenance fields) and cannot
+ * accept identity credential subjects.
+ */
+
+import { signBytes, verifyBytes } from "./sign.ts";
+import type {
+  SiteOwnershipCredentialSubject,
+  ActorDelegationCredentialSubject,
+  VCProof,
+} from "./schema.ts";
+
+export type IdentityCredentialSubject =
+  SiteOwnershipCredentialSubject | ActorDelegationCredentialSubject;
+
+/**
+ * Produce canonical UTF-8 bytes from an identity credential subject.
+ * DETERMINISM: identical inputs → identical bytes (sorted-key JSON, no whitespace).
+ */
+export function identityCredentialBytes(subject: IdentityCredentialSubject): Uint8Array {
+  const canonical = JSON.stringify(subject, Object.keys(subject).sort());
+  return new TextEncoder().encode(canonical);
+}
+
+/**
+ * Sign an identity credential subject and produce a W3C VC proof.
+ *
+ * @param subject             — identity credential subject fields
+ * @param privateKeyHex       — 32-byte Ed25519 private key as hex (from env secret)
+ * @param verificationMethod  — DID key reference (e.g. "did:web:warpgogol.com#v1")
+ * @param issuedAt            — ISO-8601 timestamp for the proof creation date
+ */
+export async function signIdentityCredential(
+  subject: IdentityCredentialSubject,
+  privateKeyHex: string,
+  verificationMethod: string,
+  issuedAt: string,
+): Promise<VCProof> {
+  const proofValue = await signBytes(privateKeyHex, identityCredentialBytes(subject));
+  return {
+    type: "Ed25519Signature2020",
+    created: issuedAt,
+    verificationMethod,
+    proofPurpose: "assertionMethod",
+    proofValue,
+  };
+}
+
+/**
+ * Verify an identity credential proof against the published public key.
+ *
+ * @param subject              — identity credential subject fields
+ * @param proof                — proof object from the credential
+ * @param publicKeyMultibase   — multibase public key from werkstatt.identity.json
+ * @returns true if signature is valid
+ */
+export async function verifyIdentityCredential(
+  subject: IdentityCredentialSubject,
+  proof: VCProof,
+  publicKeyMultibase: string,
+): Promise<boolean> {
+  return verifyBytes(publicKeyMultibase, identityCredentialBytes(subject), proof.proofValue);
+}

package/src/passport/index.ts

@@ -0,0 +1,53 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Facilitates the export of passport-related schemas, types, and utility functions for credential management.</purpose>
+<non-goals>
+  <item>Do not implement business logic for credential validation or user authentication.</item>
+  <item>Do not manage raw data parsing or transport orchestration.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * @warpgogol/werkstatt-shared/passport — Cosmic Passport
+ * DNA-31, DNA-34 / RFC-0028
+ */
+
+export {
+  PassportSchema,
+  PassportPublicKeyFileSchema,
+  PassportPublicKeyEntrySchema,
+  SiteOwnershipCredentialSubjectSchema,
+  ActorDelegationCredentialSubjectSchema,
+  WerkstattCredentialSchema,
+  WerkstattIdentityConfigSchema,
+} from "./schema.ts";
+export type {
+  PassportJson,
+  PassportPublicKeyFile,
+  PassportPublicKeyEntry,
+  VCProof,
+  VerifiableCredential,
+  SiteOwnershipCredentialSubject,
+  ActorDelegationCredentialSubject,
+  WerkstattCredential,
+  WerkstattIdentityConfig,
+} from "./schema.ts";
+
+export { rotateKey } from "./key-rotate.ts";
+export type { KeyRotateOptions, KeyRotateResult } from "./key-rotate.ts";
+
+export { signBytes, verifyBytes, generateKeypair } from "./sign.ts";
+
+export {
+  identityCredentialBytes,
+  signIdentityCredential,
+  verifyIdentityCredential,
+} from "./identity-sign.ts";
+export type { IdentityCredentialSubject } from "./identity-sign.ts";
+
+export { dhtEntryBytes, signDhtEntry, verifyDhtEntry } from "./dht-sign.ts";
+export type { DHTEntryData } from "./dht-sign.ts";

package/src/passport/key-rotate.ts

@@ -0,0 +1,133 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Facilitates the generation and rotation of Ed25519 keypairs for secure application authentication.</purpose>
+<non-goals>
+  <item>Do not handle raw key parsing or validation beyond schema checks.</item>
+  <item>Do not manage application configuration or orchestration.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * @warpgogol/werkstatt-shared/passport — Key rotation
+ *
+ * DNA-34 / RFC-0028
+ *
+ * SECURITY CONTRACT:
+ * - Private key is NEVER written to disk. It is printed to stdout ONCE
+ *   for the engineer to paste into GitHub Actions secret PASSPORT_SIGNING_KEY.
+ * - The public key file is written to apps/<app>/public/.well-known/cosmic-passport-key.json
+ *   and committed to the repository.
+ * - Old public keys remain in the file (active: false) for historical verification.
+ */
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { generateKeypair } from "./sign.ts";
+import { PassportPublicKeyFileSchema } from "./schema.ts";
+import type { PassportPublicKeyFile, PassportPublicKeyEntry } from "./schema.ts";
+
+export interface KeyRotateOptions {
+  /** Absolute path to the app directory */
+  appDirectory: string;
+  /** App identifier (from system.yaml) */
+  appId: string;
+  /** If true, this is the initial key generation (no previous key file exists) */
+  initial?: boolean;
+}
+
+export interface KeyRotateResult {
+  /** New key version string (e.g. "v2") */
+  newVersion: string;
+  /** New public key multibase — written to key file */
+  publicKeyMultibase: string;
+  /**
+   * Private key as hex string — print to stdout and discard.
+   * Store as GitHub Actions secret PASSPORT_SIGNING_KEY.
+   * NEVER log, write, or return this beyond the immediate CLI call.
+   */
+  privateKeyHex: string;
+  /** Path where the updated public key file was written */
+  publicKeyFilePath: string;
+}
+
+/**
+ * Generate a new Ed25519 keypair and update the public key file.
+ *
+ * Steps:
+ *   1. Generate new keypair
+ *   2. Load existing public key file (if any)
+ *   3. Mark all existing keys as active: false
+ *   4. Append new key as active: true
+ *   5. Write updated file to apps/<app>/public/.well-known/cosmic-passport-key.json
+ *   6. Return private key for secure storage (never written to disk)
+ *
+ * After calling this function:
+ *   - Update system.yaml release.passport.keyVersion to the new version
+ *   - Paste the returned privateKeyHex into GitHub Actions secret PASSPORT_SIGNING_KEY
+ *   - Commit the updated public key file
+ */
+export async function rotateKey(options: KeyRotateOptions): Promise<KeyRotateResult> {
+  const { appDirectory, appId, initial = false } = options;
+  const publicKeyFilePath = join(appDirectory, "public", ".well-known", "cosmic-passport-key.json");
+
+  // Step 1: Generate new keypair
+  const { privateKeyHex, publicKeyMultibase } = await generateKeypair();
+
+  // Step 2: Load existing key file
+  let existingKeys: PassportPublicKeyEntry[] = [];
+  let nextVersionNumber = 1;
+
+  if (!initial) {
+    try {
+      const raw = await readFile(publicKeyFilePath, "utf8");
+      const existing = PassportPublicKeyFileSchema.parse(JSON.parse(raw));
+      existingKeys = existing.keys;
+
+      // Determine next version number
+      const versionNumbers = existingKeys
+        .map((k) => parseInt(k.version.replace("v", ""), 10))
+        .filter((n) => !isNaN(n));
+      nextVersionNumber = Math.max(0, ...versionNumbers) + 1;
+    } catch {
+      // No existing file — treat as initial
+    }
+  }
+
+  const newVersion = `v${nextVersionNumber}`;
+
+  // Step 3: Mark existing keys inactive
+  const updatedKeys: PassportPublicKeyEntry[] = existingKeys.map((k) => ({
+    ...k,
+    active: false,
+  }));
+
+  // Step 4: Append new key
+  updatedKeys.push({
+    version: newVersion,
+    active: true,
+    type: "Ed25519VerificationKey2020",
+    publicKeyMultibase,
+    createdAt: new Date().toISOString(),
+  });
+
+  // Step 5: Write updated file
+  const updatedFile: PassportPublicKeyFile = {
+    schemaVersion: "1.0",
+    appId,
+    keys: updatedKeys,
+  };
+
+  await mkdir(dirname(publicKeyFilePath), { recursive: true });
+  await writeFile(publicKeyFilePath, JSON.stringify(updatedFile, null, 2), "utf8");
+
+  return {
+    newVersion,
+    publicKeyMultibase,
+    privateKeyHex,
+    publicKeyFilePath,
+  };
+}