Merge pull request #4 from tokenhost/feat/build-artifacts-signing

SPEC 11: th build packages artifacts + UI bundle and signs manifest

Author: snissn

.env.example

@@ -21,3 +21,12 @@ TH_PRIVATE_KEY=0xreplace_me
 # Explorer verification (future: `th verify`)
 ETHERSCAN_API_KEY=replace_me
 
+# --- Build/publish metadata (optional) ---
+# If set, th build/deploy will sign manifest.json (ed25519).
+# Provide either:
+# - TH_MANIFEST_SIGNING_KEY_PATH=/absolute/path/to/ed25519-private-key.pem
+# - TH_MANIFEST_SIGNING_KEY=base64:<pkcs8-der-base64>
+TH_MANIFEST_SIGNING_KEY_PATH=/path/to/ed25519-private-key.pem
+
+# Optional: UI base URL recorded in manifest.json (defaults to a local file:// URL for ui-bundle/).
+TH_UI_BASE_URL=https://your-app.apps.tokenhost.com/

packages/cli/src/index.ts

@@ -1,9 +1,10 @@
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
 import { spawnSync } from 'child_process';
 import { createRequire } from 'module';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { Command } from 'commander';
 
 import { generateAppSolidity } from '@tokenhost/generator';
@@ -112,6 +113,106 @@ function resolveNextExportUiTemplateDir(): string {
   );
 }
 
+function toFileUrl(p: string): string {
+  return pathToFileURL(path.resolve(p)).toString();
+}
+
+function ensureTrailingSlash(url: string): string {
+  return url.endsWith('/') ? url : `${url}/`;
+}
+
+function runCommand(cmd: string, args: string[], opts?: { cwd?: string }) {
+  const res = spawnSync(cmd, args, {
+    cwd: opts?.cwd,
+    stdio: 'inherit'
+  });
+  if (res.error && (res.error as any).code === 'ENOENT') {
+    throw new Error(`${cmd} not found on PATH. Install it and retry.`);
+  }
+  if (res.status !== 0) {
+    throw new Error(`${cmd} ${args.join(' ')} failed with exit code ${res.status ?? 'unknown'}`);
+  }
+}
+
+function runPnpmCommand(args: string[], opts?: { cwd?: string }) {
+  // Prefer local/global pnpm; fall back to corepack if pnpm isn't installed.
+  const res = spawnSync('pnpm', args, { cwd: opts?.cwd, stdio: 'inherit' });
+  if (res.error && (res.error as any).code === 'ENOENT') {
+    const res2 = spawnSync('corepack', ['pnpm', ...args], { cwd: opts?.cwd, stdio: 'inherit' });
+    if (res2.error && (res2.error as any).code === 'ENOENT') {
+      throw new Error(`pnpm not found. Install pnpm or enable corepack, then retry.`);
+    }
+    if (res2.status !== 0) {
+      throw new Error(`corepack pnpm ${args.join(' ')} failed with exit code ${res2.status ?? 'unknown'}`);
+    }
+    return;
+  }
+  if (res.status !== 0) {
+    throw new Error(`pnpm ${args.join(' ')} failed with exit code ${res.status ?? 'unknown'}`);
+  }
+}
+
+function renderThsTs(schema: ThsSchema): string {
+  // Embed the full THS schema in the UI so it can render forms + routes without server-side code.
+  return (
+    `/*\n` +
+    ` * GENERATED FILE\n` +
+    ` *\n` +
+    ` * This file is generated by \`th generate\` from the THS schema.\n` +
+    ` */\n\n` +
+    `export const ths = ${JSON.stringify(schema, null, 2)} as const;\n\n` +
+    `export type Ths = typeof ths;\n`
+  );
+}
+
+function ensureEd25519PrivateKey(key: crypto.KeyObject): crypto.KeyObject {
+  const type = (key as any).asymmetricKeyType as string | undefined;
+  if (type && type !== 'ed25519') {
+    throw new Error(`Manifest signing key must be Ed25519 (got ${type}).`);
+  }
+  return key;
+}
+
+function loadManifestSigningKey(): crypto.KeyObject | null {
+  const keyPath = process.env.TH_MANIFEST_SIGNING_KEY_PATH;
+  if (keyPath) {
+    const pem = fs.readFileSync(keyPath, 'utf-8');
+    return ensureEd25519PrivateKey(crypto.createPrivateKey(pem));
+  }
+
+  const env = process.env.TH_MANIFEST_SIGNING_KEY || process.env.TH_MANIFEST_SIGNING_PRIVATE_KEY;
+  if (!env) return null;
+
+  const raw = env.trim();
+  if (raw.startsWith('-----BEGIN')) {
+    return ensureEd25519PrivateKey(crypto.createPrivateKey(raw));
+  }
+
+  // Assume base64-encoded PKCS#8 DER.
+  const b64 = raw.startsWith('base64:') ? raw.slice('base64:'.length) : raw;
+  const der = Buffer.from(b64, 'base64');
+  return ensureEd25519PrivateKey(crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' }));
+}
+
+function computeKeyIdEd25519(privateKey: crypto.KeyObject): string {
+  const pub = crypto.createPublicKey(privateKey);
+  const spki = pub.export({ format: 'der', type: 'spki' }) as Buffer;
+  return sha256Digest(spki);
+}
+
+function signManifest(manifest: any, privateKey: crypto.KeyObject): { alg: string; keyId: string; sig: string } {
+  // Sign the canonical manifest digest of the manifest with signatures removed.
+  // Verifiers should recompute this same digest before verifying.
+  const unsigned = { ...manifest, signatures: [] };
+  const digest = computeSchemaHash(unsigned);
+  const signature = crypto.sign(null, Buffer.from(digest, 'utf-8'), privateKey);
+  return {
+    alg: 'ed25519',
+    keyId: computeKeyIdEd25519(privateKey),
+    sig: signature.toString('base64')
+  };
+}
+
 function findUp(filename: string, startDir: string): string | null {
   let dir = path.resolve(startDir);
   while (true) {
@@ -450,17 +551,7 @@ program
 
       const thsTsPath = path.join(uiDir, 'src', 'generated', 'ths.ts');
       ensureDir(path.dirname(thsTsPath));
-
-      // Embed the full THS schema in the UI so it can render forms + routes without server-side code.
-      const thsTs =
-        `/*\n` +
-        ` * GENERATED FILE\n` +
-        ` *\n` +
-        ` * This file is generated by \`th generate\` from the THS schema.\n` +
-        ` */\n\n` +
-        `export const ths = ${JSON.stringify(schema, null, 2)} as const;\n\n` +
-        `export type Ths = typeof ths;\n`;
-      fs.writeFileSync(thsTsPath, thsTs);
+      fs.writeFileSync(thsTsPath, renderThsTs(schema));
 
       console.log(`Wrote ui/ (Next.js static export template)`);
     }
@@ -472,7 +563,8 @@ program
   .command('build')
   .argument('<schema>', 'Path to THS schema JSON file')
   .option('--out <dir>', 'Output directory', 'artifacts')
-  .action((schemaPath: string, opts: { out: string }) => {
+  .option('--no-ui', 'Do not generate/build UI bundle')
+  .action((schemaPath: string, opts: { out: string; ui: boolean }) => {
     const input = readJsonFile(schemaPath);
     const structural = validateThsStructural(input);
     if (!structural.ok) {
@@ -515,14 +607,69 @@ program
     // 3) Write schema copy
     fs.writeFileSync(path.join(outDir, 'schema.json'), JSON.stringify(schema, null, 2));
 
-    // 4) Build a local (unsigned) manifest. This is spec-shaped but uses placeholders
-    // for deployments/UI until `th deploy`/`th publish` are implemented.
+    // 4) Package build artifacts (SPEC 11)
+    const sourcesTgzPath = path.join(outDir, 'sources.tgz');
+    const compiledTgzPath = path.join(outDir, 'compiled.tgz');
+    runCommand('tar', ['-czf', sourcesTgzPath, '-C', outDir, path.dirname(appSol.path)]);
+    runCommand('tar', ['-czf', compiledTgzPath, '-C', outDir, 'compiled']);
+
+    // 5) Build UI bundle (Next.js static export) (SPEC 8 / 11)
+    const emptyUiBundleDigest = computeSchemaHash({ version: 1, files: [] });
+    let uiBundleDigest = emptyUiBundleDigest;
+    let uiBaseUrl = ensureTrailingSlash(process.env.TH_UI_BASE_URL ?? 'http://localhost/');
+    let uiBundleDir: string | null = null;
+    let uiSiteDir: string | null = null;
+
+    if (opts.ui) {
+      uiBundleDir = path.join(outDir, 'ui-bundle');
+      uiSiteDir = path.join(outDir, 'ui-site');
+      fs.rmSync(uiBundleDir, { recursive: true, force: true });
+      ensureDir(uiBundleDir);
+
+      const uiWorkDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tokenhost-ui-build-'));
+      try {
+        const templateDir = resolveNextExportUiTemplateDir();
+        copyDir(templateDir, uiWorkDir);
+
+        // Inject schema for client-side routing/forms.
+        const thsTsPath = path.join(uiWorkDir, 'src', 'generated', 'ths.ts');
+        ensureDir(path.dirname(thsTsPath));
+        fs.writeFileSync(thsTsPath, renderThsTs(schema));
+
+        // Ship ABI alongside the UI so it can operate without additional servers.
+        const compiledPublicPath = path.join(uiWorkDir, 'public', 'compiled', 'App.json');
+        ensureDir(path.dirname(compiledPublicPath));
+        fs.writeFileSync(compiledPublicPath, compiledJson);
+
+        // Do not bake a manifest into the UI bundle; it is published separately and signed.
+        const bakedManifestPath = path.join(uiWorkDir, 'public', '.well-known', 'tokenhost', 'manifest.json');
+        if (fs.existsSync(bakedManifestPath)) fs.rmSync(bakedManifestPath, { force: true });
+
+        runPnpmCommand(['install'], { cwd: uiWorkDir });
+        runPnpmCommand(['build'], { cwd: uiWorkDir });
+
+        const exportedDir = path.join(uiWorkDir, 'out');
+        if (!fs.existsSync(exportedDir)) {
+          throw new Error(`UI build did not produce an export directory at ${exportedDir}.`);
+        }
+
+        // Copy the static export output into the build output directory.
+        copyDir(exportedDir, uiBundleDir);
+      } finally {
+        fs.rmSync(uiWorkDir, { recursive: true, force: true });
+      }
+
+      uiBundleDigest = computeDirectoryDigest(uiBundleDir);
+      uiBaseUrl = ensureTrailingSlash(process.env.TH_UI_BASE_URL ?? toFileUrl(uiSiteDir));
+    }
+
+    // 6) Build a local manifest. This is spec-shaped but uses placeholder deployments
+    // until `th deploy` updates it.
     const schemaHash = computeSchemaHash(schema);
     const sourcesDigest = computeDirectoryDigest(path.join(outDir, path.dirname(appSol.path)));
     const compiledDigest = computeDirectoryDigest(path.join(outDir, 'compiled'));
     const abiDigest = sha256Digest(JSON.stringify(compiled.abi));
     const bytecodeDigest = sha256Digest(compiled.bytecode);
-    const emptyUiBundleDigest = computeSchemaHash({ version: 1, files: [] });
 
     const features = {
       indexer: schema.app.features?.indexer ?? false,
@@ -559,8 +706,8 @@ program
       },
       collections,
       artifacts: {
-        soliditySources: { digest: sourcesDigest },
-        compiledContracts: { digest: compiledDigest }
+        soliditySources: { digest: sourcesDigest, url: toFileUrl(sourcesTgzPath) },
+        compiledContracts: { digest: compiledDigest, url: toFileUrl(compiledTgzPath) }
       },
       deployments: [
         {
@@ -585,14 +732,19 @@ program
         }
       ],
       ui: {
-        bundleHash: emptyUiBundleDigest,
-        baseUrl: 'http://localhost/',
+        bundleHash: uiBundleDigest,
+        baseUrl: uiBaseUrl,
         wellKnown: '/.well-known/tokenhost/manifest.json'
       },
       features,
       signatures: [{ alg: 'none', sig: 'UNSIGNED' }]
     };
 
+    const signingKey = loadManifestSigningKey();
+    if (signingKey) {
+      manifest.signatures = [signManifest(manifest, signingKey)];
+    }
+
     // Validate manifest shape against the local JSON schema.
     const { ok, errors: manifestErrors } = validateManifest(manifest);
     if (!ok) {
@@ -603,9 +755,26 @@ program
     }
 
     const manifestPath = path.join(outDir, 'manifest.json');
-    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    const manifestJsonOut = JSON.stringify(manifest, null, 2);
+    fs.writeFileSync(manifestPath, manifestJsonOut);
+
+    // Convenience: create a self-hostable static site root that includes the UI bundle + manifest.
+    // Note: ui.bundleHash is computed over ui-bundle/ (UI code only), not this directory.
+    if (uiBundleDir && uiSiteDir) {
+      fs.rmSync(uiSiteDir, { recursive: true, force: true });
+      copyDir(uiBundleDir, uiSiteDir);
+      ensureDir(path.join(uiSiteDir, '.well-known', 'tokenhost'));
+      fs.writeFileSync(path.join(uiSiteDir, '.well-known', 'tokenhost', 'manifest.json'), manifestJsonOut);
+      fs.writeFileSync(path.join(uiSiteDir, 'manifest.json'), manifestJsonOut);
+    }
     console.log(`Wrote ${appSol.path}`);
     console.log(`Wrote compiled/App.json`);
+    console.log(`Wrote sources.tgz`);
+    console.log(`Wrote compiled.tgz`);
+    if (uiBundleDir) {
+      console.log(`Wrote ui-bundle/ (digest: ${uiBundleDigest})`);
+      console.log(`Wrote ui-site/ (self-hostable static root)`);
+    }
     console.log(`Wrote manifest.json`);
   });
 
@@ -730,6 +899,18 @@ program
         throw new Error('Schema includes paid creates, but deployed contract has no treasuryAddress constructor.');
       }
 
+      // Re-sign manifest after mutating deployments.
+      const signingKey = loadManifestSigningKey();
+      if (signingKey) {
+        manifest.signatures = [signManifest(manifest, signingKey)];
+      } else {
+        const hadRealSig = Array.isArray(manifest.signatures) && manifest.signatures.some((s: any) => s && s.alg && s.alg !== 'none');
+        if (hadRealSig) {
+          console.warn('WARN manifest: signing key not provided; clearing signatures and marking UNSIGNED');
+        }
+        manifest.signatures = [{ alg: 'none', sig: 'UNSIGNED' }];
+      }
+
       const validation = validateManifest(manifest);
       if (!validation.ok) {
         throw new Error(`Updated manifest failed validation:\n${JSON.stringify(validation.errors, null, 2)}`);

test/testCliBuildArtifacts.js

@@ -0,0 +1,75 @@
+import { expect } from 'chai';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+}
+
+function runTh(args, cwd) {
+  return spawnSync('node', [path.resolve('packages/cli/dist/index.js'), ...args], {
+    cwd,
+    encoding: 'utf-8'
+  });
+}
+
+function minimalSchema(overrides = {}) {
+  return {
+    thsVersion: '2025-12',
+    schemaVersion: '0.0.1',
+    app: {
+      name: 'Build Artifacts Test',
+      slug: 'build-artifacts-test',
+      features: { uploads: false, onChainIndexing: true }
+    },
+    collections: [
+      {
+        name: 'Item',
+        fields: [{ name: 'title', type: 'string', required: true }],
+        createRules: { required: ['title'], access: 'public' },
+        visibilityRules: { gets: ['title'], access: 'public' },
+        updateRules: { mutable: ['title'], access: 'owner' },
+        deleteRules: { softDelete: true, access: 'owner' },
+        indexes: { unique: [], index: [] }
+      }
+    ],
+    ...overrides
+  };
+}
+
+describe('th build (artifacts)', function () {
+  it('emits sources.tgz + compiled.tgz + manifest (no UI)', function () {
+    this.timeout(60000);
+
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'th-build-artifacts-'));
+    const schemaPath = path.join(dir, 'schema.json');
+    const outDir = path.join(dir, 'out');
+    writeJson(schemaPath, minimalSchema());
+
+    const res = runTh(['build', schemaPath, '--out', outDir, '--no-ui'], process.cwd());
+    expect(res.status, res.stderr || res.stdout).to.equal(0);
+
+    for (const p of [
+      'schema.json',
+      'contracts/App.sol',
+      'compiled/App.json',
+      'manifest.json',
+      'sources.tgz',
+      'compiled.tgz'
+    ]) {
+      expect(fs.existsSync(path.join(outDir, p)), `missing ${p}`).to.equal(true);
+    }
+
+    expect(fs.existsSync(path.join(outDir, 'ui-bundle'))).to.equal(false);
+    expect(fs.existsSync(path.join(outDir, 'ui-site'))).to.equal(false);
+
+    const manifest = JSON.parse(fs.readFileSync(path.join(outDir, 'manifest.json'), 'utf-8'));
+    expect(manifest?.artifacts?.soliditySources?.url).to.match(/^file:\/\//);
+    expect(manifest?.artifacts?.compiledContracts?.url).to.match(/^file:\/\//);
+    expect(manifest?.signatures?.[0]?.sig).to.be.a('string');
+  });
+});
+