githolon 0.21.0 → 0.22.0

package/dist/cli.mjs

@@ -12,12 +12,18 @@ var __export = (target, all) => {
 // src/governance.ts
 var governance_exports = {};
 __export(governance_exports, {
+  governanceOffer: () => governanceOffer,
+  governanceRelay: () => governanceRelay,
   grantOrRevoke: () => grantOrRevoke,
   keyEnroll: () => keyEnroll,
+  keyExport: () => keyExport,
+  keyImport: () => keyImport,
   keyShow: () => keyShow,
   resolveGovernancePrincipal: () => resolveGovernancePrincipal,
   signAndPostGovernance: () => signAndPostGovernance
 });
+import { createHash, createPrivateKey, createPublicKey } from "node:crypto";
+import { readFileSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { connect } from "@githolon/client";
 async function connectGovernance(cloud, parent) {
   const authToken = await sessionToken().catch(() => void 0);
@@ -155,6 +161,174 @@ async function keyShow(opts) {
   out(`  keyHash ${device.keyHash} (the on-chain key:<hash> leaf; secret stays local)`);
   return 0;
 }
+function deviceKeyFromSeed(seed) {
+  if (seed.length !== 32) throw new Error(`an ed25519 seed is 32 bytes; got ${seed.length}`);
+  const pkcs8 = Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), seed]);
+  const pub = Buffer.from(
+    createPublicKey(createPrivateKey({ key: pkcs8, format: "der", type: "pkcs8" })).export({ format: "der", type: "spki" }).subarray(-32)
+  );
+  return { secret: seed.toString("base64"), public: pub.toString("base64"), keyHash: createHash("sha256").update(pub).digest("hex") };
+}
+function seedFromInput(input, opts) {
+  const v = input.trim();
+  if (opts.sha256 === true) return createHash("sha256").update(v).digest();
+  if (opts.format === "hex" || opts.format === void 0 && /^[0-9a-fA-F]{64}$/.test(v)) return Buffer.from(v, "hex");
+  if (opts.format === "base64" || opts.format === void 0) {
+    const b = Buffer.from(v, "base64");
+    if (b.length === 32) return b;
+    if (opts.format === "base64") throw new Error(`--secret base64 decoded to ${b.length} bytes, not a 32-byte seed`);
+  }
+  throw new Error(
+    "--secret is not a 32-byte ed25519 seed \u2014 pass a base64 seed, a 64-hex seed (--format hex is auto-detected), or --sha256 to derive the seed from a passphrase/preimage"
+  );
+}
+async function keyImport(opts) {
+  const principal = opts.principal ?? currentPrincipal();
+  if (principal === void 0) {
+    err("key import needs --principal <uid> (the auth-uid this key authors as)");
+    return 1;
+  }
+  if (opts.secret === void 0 || opts.secret === "") {
+    err("key import needs --secret <hex|base64 ed25519 seed> (or --sha256 to derive the seed from a passphrase)");
+    return 1;
+  }
+  let key;
+  try {
+    key = deviceKeyFromSeed(seedFromInput(opts.secret, opts));
+  } catch (e) {
+    err(e.message);
+    return 1;
+  }
+  const existing = getDeviceKey(principal);
+  if (existing !== void 0 && existing.keyHash !== key.keyHash && opts.yes !== true) {
+    err(`a DIFFERENT key is already stored for ${principal} (keyHash ${existing.keyHash.slice(0, 12)}\u2026) \u2014 re-run with --yes to replace it`);
+    return 1;
+  }
+  setDeviceKey(principal, key);
+  out(`\u2713 imported signing key for ${principal}`);
+  out(`  keyHash ${key.keyHash}`);
+  out(`  public  ${key.public}  (secret stored 0600 in ~/.holon)`);
+  out(`  now: githolon gov <ws> <directive> --as ${principal}   (if not yet enrolled there: githolon key enroll --principal ${principal} --parent <ws>)`);
+  return 0;
+}
+async function keyExport(opts) {
+  const principal = opts.principal ?? currentPrincipal();
+  if (principal === void 0) {
+    err("key export needs --principal <uid>");
+    return 1;
+  }
+  const device = getDeviceKey(principal);
+  if (device === void 0) {
+    out(`no signing key on file for ${principal}`);
+    return 0;
+  }
+  if (opts.yes !== true) {
+    err(`key export prints the SECRET seed for ${principal} to stdout \u2014 re-run with --yes to confirm`);
+    return 1;
+  }
+  out(`signing key for ${principal} (KEEP SECRET):`);
+  out(`  secret  ${device.secret}   (base64 ed25519 seed \u2014 = githolon key import --secret <this>)`);
+  out(`  public  ${device.public}`);
+  out(`  keyHash ${device.keyHash}`);
+  return 0;
+}
+function buildOfferPayload(opts) {
+  const raw = opts.payloadFile !== void 0 ? readFileSync(opts.payloadFile, "utf8") : opts.payload;
+  let payload = {};
+  if (raw !== void 0 && raw.trim() !== "") payload = JSON.parse(raw);
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    throw new Error("payload must be a JSON object");
+  }
+  const p = payload;
+  if (opts.stamp === true) {
+    const now = Date.now();
+    for (const f of ["requestedAt", "grantedAt", "revokedAt", "setAt"]) if (!(f in p)) p[f] = now;
+    if (!("bornAt" in p)) p["bornAt"] = new Date(now).toISOString();
+  }
+  return p;
+}
+async function governanceOffer(ws, directiveId, opts) {
+  let payload;
+  try {
+    payload = buildOfferPayload(opts);
+  } catch (e) {
+    err(`--payload: ${e.message}`);
+    return 1;
+  }
+  let principal;
+  try {
+    principal = resolveGovernancePrincipal(opts);
+  } catch (e) {
+    err(e.message);
+    return 1;
+  }
+  if (opts.save !== void 0) {
+    try {
+      const holon = await connectGovernance(cloudBase(opts.cloud), ws);
+      const device = await ensureDeviceKey(holon, principal);
+      const sealed = await holon.signGovernanceOffer({ directiveId, payload, authorSecret: device.secret, actor: `user:${principal}` });
+      writeFileSync2(opts.save, JSON.stringify({ ws, directiveId, principal, intentBytes: sealed.intentBytes }, null, 2) + "\n");
+    } catch (e) {
+      err(e.message);
+      return 1;
+    }
+    out(`\u2713 authored + signed ${directiveId} for ${ws} \u2192 ${opts.save} (not relayed)`);
+    out(`  relay it (the only step that needs the cloud): githolon gov relay ${ws} ${opts.save}`);
+    return 0;
+  }
+  let v;
+  try {
+    v = await signAndPostGovernance(ws, directiveId, payload, opts);
+  } catch (e) {
+    err(e.message);
+    return 1;
+  }
+  if (!v.ok) {
+    err(`${directiveId} refused (${v.status}): ${typeof v.body === "string" ? v.body : JSON.stringify(v.body)}`);
+    return 1;
+  }
+  const head = v.body?.head;
+  out(`\u2713 ${directiveId} admitted at ${ws} via signed offer (as ${principal})${head !== void 0 ? ` \u2014 head ${head.slice(0, 12)}\u2026` : ""}`);
+  return 0;
+}
+async function governanceRelay(ws, file, opts) {
+  let saved;
+  try {
+    saved = JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    err(`cannot read offer file ${file}: ${e.message}`);
+    return 1;
+  }
+  const { directiveId, intentBytes } = saved;
+  if (typeof directiveId !== "string" || typeof intentBytes !== "string") {
+    err(`${file} is not a saved offer (expected { directiveId, intentBytes })`);
+    return 1;
+  }
+  const cloud = cloudBase(opts.cloud);
+  let r;
+  try {
+    r = await fetch(`${cloud}/v2/workspaces/${ws}/${directiveId}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ intentBytes })
+    });
+  } catch (e) {
+    err(`relay to ${ws} failed: ${e.message}`);
+    return 1;
+  }
+  const text = await r.text();
+  if (!r.ok) {
+    err(`${directiveId} refused (${r.status}): ${text}`);
+    return 1;
+  }
+  let head;
+  try {
+    head = JSON.parse(text).head;
+  } catch {
+  }
+  out(`\u2713 relayed ${directiveId} to ${ws}${head !== void 0 ? ` \u2014 head ${head.slice(0, 12)}\u2026` : ""}`);
+  return 0;
+}
 var out, err;
 var init_governance = __esm({
   "src/governance.ts"() {
@@ -192,7 +366,7 @@ __export(cloud_exports, {
   wsRetire: () => wsRetire,
   wsStatus: () => wsStatus
 });
-import { chmodSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { chmodSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "node:fs";
 import { join as join2 } from "node:path";
 import { homedir } from "node:os";
 function cloudBase(flag) {
@@ -212,11 +386,11 @@ function credsPath() {
 }
 function loadCreds() {
   if (!existsSync2(credsPath())) return { version: 1, secrets: {} };
-  return JSON.parse(readFileSync(credsPath(), "utf8"));
+  return JSON.parse(readFileSync2(credsPath(), "utf8"));
 }
 function saveCreds(c) {
   mkdirSync2(configDir(), { recursive: true });
-  writeFileSync2(credsPath(), JSON.stringify(c, null, 2) + "\n", "utf8");
+  writeFileSync3(credsPath(), JSON.stringify(c, null, 2) + "\n", "utf8");
   chmodSync(credsPath(), 384);
 }
 function getSecret(cloud, ws) {
@@ -475,7 +649,7 @@ async function deploy(ws, opts) {
   const r = await fetch(`${cloud}/v2/workspaces/${ws}/domains`, {
     method: "POST",
     headers: { "content-type": "application/json" },
-    body: readFileSync(file, "utf8")
+    body: readFileSync2(file, "utf8")
   });
   const d = await r.json().catch(() => void 0);
   if (!r.ok || d?.ok !== true) {
@@ -1028,7 +1202,7 @@ var init_engine = __esm({
 
 // src/local_holon.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync2, statSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname2, join as join4 } from "node:path";
 import { File as File2, Directory as Directory2 } from "@bjorn3/browser_wasi_shim";
 async function fetchJsonCached(url, cacheFile) {
@@ -1037,10 +1211,10 @@ async function fetchJsonCached(url, cacheFile) {
     if (!r.ok) throw new Error(`${url} \u2192 ${r.status}`);
     const text = await r.text();
     mkdirSync3(dirname2(cacheFile), { recursive: true });
-    writeFileSync3(cacheFile, text, "utf8");
+    writeFileSync4(cacheFile, text, "utf8");
     return JSON.parse(text);
   } catch (e) {
-    if (existsSync3(cacheFile)) return JSON.parse(readFileSync2(cacheFile, "utf8"));
+    if (existsSync3(cacheFile)) return JSON.parse(readFileSync3(cacheFile, "utf8"));
     throw e;
   }
 }
@@ -1050,7 +1224,7 @@ async function fetchRuntime(cloud) {
   const wasmCache = join4(cache, "holon.wasm");
   const localWasm = process.env["NOMOS_LOCAL_WASM"];
   if (localWasm) {
-    const bytes = readFileSync2(localWasm);
+    const bytes = readFileSync3(localWasm);
     const packages2 = await fetchJsonCached(`${cloud}/v1/runtime/packages`, join4(cache, "packages.json"));
     return { wasmBytes: bytes, packages: packages2 };
   }
@@ -1059,10 +1233,10 @@ async function fetchRuntime(cloud) {
     if (!r.ok) throw new Error(`runtime wasm \u2192 ${r.status}`);
     wasmBytes = new Uint8Array(await r.arrayBuffer());
     mkdirSync3(cache, { recursive: true });
-    writeFileSync3(wasmCache, wasmBytes);
+    writeFileSync4(wasmCache, wasmBytes);
   } catch (e) {
     if (!existsSync3(wasmCache)) throw e;
-    wasmBytes = readFileSync2(wasmCache);
+    wasmBytes = readFileSync3(wasmCache);
   }
   const packages = await fetchJsonCached(`${cloud}/v1/runtime/packages`, join4(cache, "packages.json"));
   return { wasmBytes, packages };
@@ -1072,7 +1246,7 @@ function writeTreeToDisk(dir, diskPath) {
   for (const [name, inode] of dir.contents) {
     const p = join4(diskPath, name);
     if (inode.contents instanceof Map) writeTreeToDisk(inode, p);
-    else writeFileSync3(p, inode.data ?? new Uint8Array(0));
+    else writeFileSync4(p, inode.data ?? new Uint8Array(0));
   }
 }
 function readTreeFromDisk(diskPath) {
@@ -1080,7 +1254,7 @@ function readTreeFromDisk(diskPath) {
   for (const name of readdirSync2(diskPath)) {
     const p = join4(diskPath, name);
     if (statSync(p).isDirectory()) contents.set(name, readTreeFromDisk(p));
-    else contents.set(name, new File2(readFileSync2(p)));
+    else contents.set(name, new File2(readFileSync3(p)));
   }
   return new Directory2(contents);
 }
@@ -1137,7 +1311,7 @@ __export(proof_offline_exports, {
   runOfflineLegs: () => runOfflineLegs,
   runOfflineProofStandalone: () => runOfflineProofStandalone
 });
-import { existsSync as existsSync5, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "node:fs";
 import { basename, dirname as dirname3, join as join6 } from "node:path";
 function parseOfflineLegs(proofSource) {
   if (!proofSource.includes("AUTO-GENERATED by nomos-compile")) {
@@ -1300,7 +1474,7 @@ function runChildBirthLeg(eng, ws, lawHash, cb, frameworkHash) {
   return done(true);
 }
 async function runOfflineProofStandalone(proofPath, cloud, domain) {
-  const src = readFileSync3(proofPath, "utf8");
+  const src = readFileSync4(proofPath, "utf8");
   const packageName = basename(proofPath).replace(/\.proof\.mts$/, "");
   const deployFile = join6(dirname3(proofPath), `${packageName}.deploy.json`);
   if (!existsSync5(deployFile)) {
@@ -1309,7 +1483,7 @@ async function runOfflineProofStandalone(proofPath, cloud, domain) {
   let legs;
   const legsFile = join6(dirname3(proofPath), `${packageName}.proof-legs.json`);
   if (existsSync5(legsFile)) {
-    const index = JSON.parse(readFileSync3(legsFile, "utf8"));
+    const index = JSON.parse(readFileSync4(legsFile, "utf8"));
     const keys = Object.keys(index.domains);
     const chosen = domain ?? index.default;
     if (index.domains[chosen] === void 0) {
@@ -1327,7 +1501,7 @@ async function runOfflineProofStandalone(proofPath, cloud, domain) {
     if (domain !== void 0) throw new Error(`--domain needs a per-domain legs index (build/${packageName}.proof-legs.json) \u2014 recompile with \`githolon compile\` to emit it`);
     legs = parseOfflineLegs(src);
   }
-  const deployBody = JSON.parse(readFileSync3(deployFile, "utf8"));
+  const deployBody = JSON.parse(readFileSync4(deployFile, "utf8"));
   const lawHash = await sha256hex(deployBody.packageUsda);
   console.log(`githolon proof \u2014 OFFLINE legs on a local holon (the cloud loop: githolon proof --live)`);
   const { eng } = await holonEngine(cloud, deployBody, "githolon-proof");
@@ -1355,7 +1529,7 @@ var init_proof_offline = __esm({
 });
 
 // src/cli.ts
-import { existsSync as existsSync9, readdirSync as readdirSync4, readFileSync as readFileSync9 } from "node:fs";
+import { existsSync as existsSync9, readdirSync as readdirSync4, readFileSync as readFileSync10 } from "node:fs";
 import { spawnSync as spawnSync4 } from "node:child_process";
 import { createRequire as createRequire2 } from "node:module";
 import { dirname as dirname5, join as join10, resolve as resolve2 } from "node:path";
@@ -1594,7 +1768,7 @@ function compileAsync(cwd, args = []) {
 // src/dev.ts
 init_engine();
 init_cloud();
-import { existsSync as existsSync6, readFileSync as readFileSync4, watch } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync5, watch } from "node:fs";
 import { createServer } from "node:http";
 import { dirname as dirname4, join as join7, resolve } from "node:path";
 import { pathToFileURL as pathToFileURL3 } from "node:url";
@@ -1776,7 +1950,7 @@ function readDeployBody(cwd, packageName) {
   if (!existsSync6(file)) {
     throw new Error(`compile produced no ${file} \u2014 check the compile output above`);
   }
-  return JSON.parse(readFileSync4(file, "utf8"));
+  return JSON.parse(readFileSync5(file, "utf8"));
 }
 async function installLaw(s, deployBody, installedBy) {
   const newHash = await sha256hex(deployBody.packageUsda);
@@ -1796,7 +1970,7 @@ async function runProofCycle(s, cwd, deployBody, installedBy) {
   if (!existsSync6(proofPath)) return void 0;
   const scratch = `proof-${s.cycle}`;
   try {
-    const legs = parseOfflineLegs(readFileSync4(proofPath, "utf8"));
+    const legs = parseOfflineLegs(readFileSync5(proofPath, "utf8"));
     await mountFresh(s.eng, scratch);
     author(s.eng, scratch, "bootstrap", "installDomain", installPayload(s.eng.hashes.nomos, s.eng.nomosPkg, installedBy), "");
     author(s.eng, scratch, "nomos", "installDomain", installPayload(s.lawHash, deployBody.packageUsda, installedBy), s.eng.hashes.nomos);
@@ -1964,7 +2138,7 @@ ${run.output}`);
 init_cloud();
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { randomBytes as randomBytes2 } from "node:crypto";
-import { readFileSync as readFileSync5 } from "node:fs";
+import { readFileSync as readFileSync6 } from "node:fs";
 var out5 = (s) => void process.stdout.write(s + "\n");
 var err5 = (s) => void process.stderr.write("error: " + s + "\n");
 function git(args, opts = {}) {
@@ -1993,7 +2167,7 @@ function workspaceFromPath(path) {
 }
 async function gitCredential(action) {
   if (action !== "get") return 0;
-  const kv = parseCredentialInput(readFileSync5(0, "utf8"));
+  const kv = parseCredentialInput(readFileSync6(0, "utf8"));
   const ws = workspaceFromPath(kv["path"]);
   if (kv["protocol"] !== "https" || ws === void 0) return 0;
   const cloud = `https://${kv["host"]}`;
@@ -2145,14 +2319,41 @@ var HELP = {
     examples: ["githolon ws create my-guestbook", "githolon ws create app1 --via co2", "githolon ws status", "githolon ws retire my-guestbook"]
   },
   key: {
-    usage: "githolon key <enroll|show> [--principal <uid>] [--parent <ws>] [--cloud <url>]",
-    what: "The signing DEVICE KEY (ed25519) the SIGNED-governance lane authors with. `enroll` mints one\n(if needed) and enrolls its PUBLIC half on-chain (a signed enrollSigner offer at the parent,\ndefault root) so the warrant gate can prove this device authors as the principal; `show` prints\nthe public identity. The SECRET stays in ~/.holon/credentials.json (0600) \u2014 never on chain.",
+    usage: "githolon key <enroll|show|import|export> [--principal <uid>] [--secret <key>] [--sha256] [--format hex|base64] [--parent <ws>] [--yes]",
+    what: "The signing DEVICE KEY (ed25519) the SIGNED-governance lane authors with. `enroll` mints one\n(if needed) and enrolls its PUBLIC half on-chain (a signed enrollSigner offer at the parent,\ndefault root) so the warrant gate can prove this device authors as the principal. `import` brings\nan EXISTING admin key you already hold into ~/.holon \u2014 pass a base64 seed, a 64-hex seed\n(auto-detected; or --format hex), or --sha256 to derive the seed from a passphrase/preimage.\n`show` prints the public identity; `export --yes` prints the SECRET seed (backup/move). The\nsecret stays in ~/.holon/credentials.json (0600) \u2014 never on chain.",
     flags: [
       ["--principal <p>", "the principal the key authors as (default: the logged-in session uid)"],
-      ["--parent <ws>", "the governance workspace to enroll at (default root)"],
+      ["--secret <key>", "import: the ed25519 seed (base64 or 64-hex), or a passphrase with --sha256"],
+      ["--sha256", "import: derive the seed as sha256(--secret) (a passphrase/preimage)"],
+      ["--format <f>", "import: force hex|base64 interpretation (default: auto-detect)"],
+      ["--parent <ws>", "enroll: the governance workspace to enroll at (default root)"],
+      ["--yes", "export: confirm printing the secret to stdout"]
+    ],
+    examples: [
+      "githolon key enroll",
+      "githolon key import --principal 32c7100e-\u2026 --secret 21c23da3\u2026   # a 64-hex admin seed",
+      "githolon key import --principal d205ca94-\u2026 --secret 'copak_\u2026' --sha256",
+      "githolon key show",
+      "githolon key export --principal 32c7100e-\u2026 --yes"
+    ]
+  },
+  gov: {
+    usage: "githolon gov <ws> <directiveId> [--payload <json> | --payload-file <f>] [--as <uid>] [--stamp] [--save <f>] [--cloud <url>]\n       githolon gov relay <ws> <offer-file> [--cloud <url>]",
+    what: "Author ANY `workspaces` governance directive as a SIGNED offer to <ws> and relay it \u2014 the generic\nlane the grant/ws/key verbs are sugar over. The directive is planned against <ws>'s OWN folded law\n(we connect + sign locally with your enrolled key; the host relays opaque {intentBytes} and the\nkernel re-verifies the signature). SIGNING IS LOCAL: with --save it writes the sealed offer WITHOUT\nrelaying \u2014 sign now, relay later/elsewhere with `gov relay` (the only step that touches the cloud).\nThe acting principal needs an enrolled signing key (githolon key enroll | key import).",
+    flags: [
+      ["--payload <json>", `the directive payload as a JSON object string ('{"name":"\u2026"}')`],
+      ["--payload-file <f>", "read the payload JSON from a file instead"],
+      ["--as <uid>", "the principal to author as (alias of --principal; default: session uid)"],
+      ["--stamp", "fill any missing requestedAt/grantedAt/revokedAt/setAt (epoch ms) + bornAt (ISO) with now"],
+      ["--save <f>", "author + sign, write the sealed offer to <f>, do NOT relay"],
       ["--cloud <url>", "target cloud"]
     ],
-    examples: ["githolon key enroll", "githolon key show"]
+    examples: [
+      `githolon gov root grantCreation --payload '{"principal":"d205ca94-\u2026"}' --as 32c7100e-\u2026 --stamp`,
+      "githolon gov co2-platform birthHome --payload-file home.json --as d205ca94-\u2026",
+      "githolon gov root birthChild --payload-file co2.json --as 32c7100e-\u2026 --save co2.offer.json",
+      "githolon gov relay root co2.offer.json"
+    ]
   },
   grant: {
     usage: "githolon grant <admin|creation|quota> <principal> [--max <N>] [--label <L>] [--parent <ws>] [--cloud <url>]",
@@ -2221,7 +2422,7 @@ init_engine();
 init_cloud();
 init_local_holon();
 import { spawnSync as spawnSync3 } from "node:child_process";
-import { existsSync as existsSync7, readdirSync as readdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync7, readdirSync as readdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "node:fs";
 import { join as join8 } from "node:path";
 var out6 = (s) => void process.stdout.write(s + "\n");
 var err6 = (s) => void process.stderr.write("error: " + s + "\n");
@@ -2239,7 +2440,7 @@ async function ledgerInit(dir, opts) {
     err6(e.message);
     return 1;
   }
-  const deployBody = JSON.parse(readFileSync6(deployFile, "utf8"));
+  const deployBody = JSON.parse(readFileSync7(deployFile, "utf8"));
   const domainHash = await sha256hex(deployBody.packageUsda);
   const c = loadCreds();
   const principal = await sessionToken().catch(() => void 0) !== void 0 ? c.session.uid : c.principal;
@@ -2258,7 +2459,7 @@ async function ledgerInit(dir, opts) {
   const gitDir = join8(dir, ".git");
   writeTreeToDisk(gitTree, gitDir);
   const cfgPath = join8(gitDir, "config");
-  writeFileSync4(cfgPath, readFileSync6(cfgPath, "utf8").replace(/bare = true/, "bare = false"), "utf8");
+  writeFileSync5(cfgPath, readFileSync7(cfgPath, "utf8").replace(/bare = true/, "bare = false"), "utf8");
   spawnSync3("git", ["-C", dir, "reset", "--hard", "main"], { stdio: "ignore" });
   out6(`\u2713 holon written \u2192 ${dir} (a normal git repo; git log IS the audit trail)`);
   out6(`
@@ -2549,7 +2750,7 @@ async function decrypt(ws, opts) {
 // src/status.ts
 init_engine();
 init_cloud();
-import { readFileSync as readFileSync8 } from "node:fs";
+import { readFileSync as readFileSync9 } from "node:fs";
 var out9 = (s) => void process.stdout.write(s + "\n");
 var err9 = (s) => void process.stderr.write("error: " + s + "\n");
 function lawDiffVerdict(localHash, installed, ws) {
@@ -2594,7 +2795,7 @@ async function status(wsArg, opts) {
   }
   let localHash;
   try {
-    const body = JSON.parse(readFileSync8(discoverDeployJson(process.cwd(), opts.file), "utf8"));
+    const body = JSON.parse(readFileSync9(discoverDeployJson(process.cwd(), opts.file), "utf8"));
     if (typeof body.packageUsda === "string") localHash = await sha256hex(body.packageUsda);
   } catch {
     localHash = void 0;
@@ -2662,9 +2863,14 @@ Identity (~/.holon/credentials.json \u2014 sessions auto-refresh):
   githolon logout                                         clear the session (workspace secrets kept)
   githolon key enroll [--principal <uid>] [--parent <ws>] mint a signing device key + enroll it on-chain
                                                        (secret stays local; warrants SIGNED governance)
-  githolon key show [--principal <uid>]                   the device key's public identity (never the secret)
+  githolon key import --principal <uid> --secret <key>    bring an EXISTING admin key into ~/.holon (accepts
+                                                       hex / base64 seed, or --sha256 <passphrase>)
+  githolon key show | export [--principal <uid>]          the device key's public identity (export --yes: secret)
 
 Governance (SIGNED client-side, relayed as {intentBytes} \u2014 never a host-author endpoint):
+  githolon gov <ws> <directive> [--payload <json>]        author ANY workspaces directive as a signed offer
+            [--as <uid>] [--stamp] [--save <file>]        to <ws> (--save signs without relaying; relay later)
+  githolon gov relay <ws> <offer-file>                    relay a saved offer (the only step that hits the cloud)
   githolon grant <admin|creation> <principal> [--label L] grant authority at the parent (default root)
   githolon grant quota <principal> --max <N>              grant a per-principal workspace allowance
   githolon revoke <admin|creation> <principal>            revoke it (the revoked fact rides the chain)
@@ -2708,18 +2914,28 @@ Options:
 function cloudArgs(rest) {
   const pos = [];
   const opts = {};
-  const VALUE_FLAGS = ["--cloud", "--principal", "--file", "--target", "--parent", "--via", "--max", "--label"];
+  const VALUE_FLAGS = ["--cloud", "--principal", "--as", "--file", "--target", "--parent", "--via", "--max", "--label", "--secret", "--payload", "--payload-file", "--save", "--format"];
+  const BOOL_FLAGS = ["--sha256", "--stamp", "--yes"];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
-    if (VALUE_FLAGS.includes(a)) {
+    if (BOOL_FLAGS.includes(a)) {
+      if (a === "--sha256") opts.sha256 = true;
+      else if (a === "--stamp") opts.stamp = true;
+      else opts.yes = true;
+    } else if (VALUE_FLAGS.includes(a)) {
       const v = rest[++i];
       if (v === void 0) return { pos, opts, bad: `${a} requires a value` };
       if (a === "--cloud") opts.cloud = v;
-      else if (a === "--principal") opts.principal = v;
+      else if (a === "--principal" || a === "--as") opts.principal = v;
       else if (a === "--target") opts.target = v;
       else if (a === "--parent") opts.parent = v;
       else if (a === "--via") opts.via = v;
       else if (a === "--label") opts.label = v;
+      else if (a === "--secret") opts.secret = v;
+      else if (a === "--payload") opts.payload = v;
+      else if (a === "--payload-file") opts.payloadFile = v;
+      else if (a === "--save") opts.save = v;
+      else if (a === "--format") opts.format = v;
       else if (a === "--max") {
         const n = Number(v);
         if (!Number.isInteger(n) || n <= 0) return { pos, opts, bad: `--max requires a positive integer` };
@@ -2849,7 +3065,7 @@ async function runProof(args) {
   if (tsxDir === void 0) {
     return refuse("tsx not found \u2014 add @githolon/dsl to your project's dependencies (tsx rides along) and npm install");
   }
-  const tsxPkg = JSON.parse(readFileSync9(join10(tsxDir, "package.json"), "utf8"));
+  const tsxPkg = JSON.parse(readFileSync10(join10(tsxDir, "package.json"), "utf8"));
   const tsxBinRel = typeof tsxPkg.bin === "string" ? tsxPkg.bin : tsxPkg.bin?.["tsx"];
   const tsxCli = join10(tsxDir, tsxBinRel ?? "dist/cli.mjs");
   console.log("githolon proof --live \u2014 the full cloud loop (throwaway workspace, retired on exit" + (keep ? "; --keep: kept, secret printed once" : "") + ")");
@@ -3041,11 +3257,40 @@ ${USAGE}`);
     const [sub] = pos;
     if (sub === "enroll") return keyEnroll(opts);
     if (sub === "show") return keyShow(opts);
-    process.stderr.write(`error: expected: githolon key <enroll|show> [--principal <uid>] [--parent <ws>]
+    if (sub === "import") return keyImport(opts);
+    if (sub === "export") return keyExport(opts);
+    process.stderr.write(`error: expected: githolon key <enroll|show|import|export> [--principal <uid>]
 
 ${USAGE}`);
     return 1;
   }
+  if (argv[0] === "gov") {
+    const { pos, opts, bad } = cloudArgs(argv.slice(1));
+    if (bad !== void 0) {
+      process.stderr.write(`error: ${bad}
+
+${commandHelp("gov") ?? USAGE}`);
+      return 1;
+    }
+    if (pos[0] === "relay") {
+      const [, ws2, file] = pos;
+      if (ws2 === void 0 || file === void 0) {
+        process.stderr.write(`error: expected: githolon gov relay <ws> <offer-file>
+
+${commandHelp("gov") ?? USAGE}`);
+        return 1;
+      }
+      return governanceRelay(ws2, file, opts);
+    }
+    const [ws, directiveId] = pos;
+    if (ws === void 0 || directiveId === void 0) {
+      process.stderr.write(`error: expected: githolon gov <ws> <directiveId> [--payload <json>] [--as <uid>]
+
+${commandHelp("gov") ?? USAGE}`);
+      return 1;
+    }
+    return governanceOffer(ws, directiveId, opts);
+  }
   if (argv[0] === "grant" || argv[0] === "revoke") {
     const verb = argv[0];
     const { pos, opts, bad } = cloudArgs(argv.slice(1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "githolon",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "description": "githolon — the Nomos developer CLI: Rails-style generators for @githolon/dsl domains + the package compiler. Kernel-independent.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -27,8 +27,8 @@
   },
   "dependencies": {
     "@bjorn3/browser_wasi_shim": "0.4.2",
-    "@githolon/client": "^0.21.0",
-    "@githolon/dsl": "^0.21.0",
+    "@githolon/client": "^0.22.0",
+    "@githolon/dsl": "^0.22.0",
     "isomorphic-git": "^1.38.4"
   },
   "devDependencies": {