@mterminal/mtx 0.1.0

package/src/lib/pack.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { unzipSync } from 'fflate'
+import { pack } from './pack'
+import { generateKeyPair } from './sign'
+
+describe('pack', () => {
+  let cwd: string
+
+  beforeEach(async () => {
+    cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'mtx-pack-'))
+  })
+
+  afterEach(async () => {
+    await fs.rm(cwd, { recursive: true, force: true })
+  })
+
+  async function scaffold(extras?: { capabilities?: string[]; allowedNetworkDomains?: string[] }) {
+    const pkg = {
+      name: 'mterminal-plugin-pack-demo',
+      version: '0.2.0',
+      main: 'dist/main.cjs',
+      engines: { 'mterminal-api': '^1.0.0' },
+      mterminal: {
+        id: 'pack-demo',
+        displayName: 'pack demo',
+        category: 'other',
+        publisher: { authorId: '', keyId: '' },
+        activationEvents: ['onStartupFinished'],
+        capabilities: extras?.capabilities ?? ['clipboard'],
+        allowedNetworkDomains: extras?.allowedNetworkDomains ?? [],
+        contributes: {},
+      },
+    }
+    await fs.writeFile(path.join(cwd, 'package.json'), JSON.stringify(pkg, null, 2))
+    await fs.mkdir(path.join(cwd, 'dist'), { recursive: true })
+    await fs.writeFile(
+      path.join(cwd, 'dist', 'main.cjs'),
+      'module.exports = { activate(){}, deactivate(){} }\n',
+    )
+    await fs.writeFile(path.join(cwd, 'README.md'), '# pack-demo\n')
+  }
+
+  it('packs a working extension and rewrites publisher fields', async () => {
+    await scaffold()
+    const { priv } = await generateKeyPair()
+    const result = await pack({
+      cwd,
+      authorId: 'gh-99',
+      keyId: 'gh-99:key1',
+      privKey: priv,
+    })
+    expect(result.manifestId).toBe('pack-demo')
+    expect(result.version).toBe('0.2.0')
+
+    const entries = unzipSync(result.buf)
+    expect(Object.keys(entries).sort()).toEqual([
+      'README.md',
+      'dist/main.cjs',
+      'package.json',
+      'signature.sig',
+    ])
+
+    const pkg = JSON.parse(new TextDecoder().decode(entries['package.json']!))
+    expect(pkg.mterminal.publisher.authorId).toBe('gh-99')
+    expect(pkg.mterminal.publisher.keyId).toBe('gh-99:key1')
+  })
+
+  it('refuses to pack an invalid manifest', async () => {
+    const pkg = {
+      name: 'mterminal-plugin-bad',
+      version: 'not-a-semver',
+      main: 'dist/main.cjs',
+      engines: { 'mterminal-api': '^1.0.0' },
+      mterminal: {
+        id: 'BadId',
+        publisher: { authorId: '', keyId: '' },
+        activationEvents: ['onStartupFinished'],
+        capabilities: [],
+        contributes: {},
+      },
+    }
+    await fs.writeFile(path.join(cwd, 'package.json'), JSON.stringify(pkg))
+    await fs.mkdir(path.join(cwd, 'dist'), { recursive: true })
+    await fs.writeFile(path.join(cwd, 'dist', 'main.cjs'), 'module.exports = {}\n')
+
+    const { priv } = await generateKeyPair()
+    await expect(
+      pack({ cwd, authorId: 'gh-1', keyId: 'gh-1:key1', privKey: priv }),
+    ).rejects.toThrow(/manifest invalid/)
+  })
+
+  it('produces signature.sig that matches the deterministic hash', async () => {
+    await scaffold()
+    const { priv } = await generateKeyPair()
+    const a = await pack({ cwd, authorId: 'gh-1', keyId: 'gh-1:key1', privKey: priv })
+    const b = await pack({ cwd, authorId: 'gh-1', keyId: 'gh-1:key1', privKey: priv })
+    const sigA = unzipSync(a.buf)['signature.sig']!
+    const sigB = unzipSync(b.buf)['signature.sig']!
+    expect(new TextDecoder().decode(sigA)).toBe(new TextDecoder().decode(sigB))
+  })
+})

package/src/lib/pack.ts

@@ -0,0 +1,93 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { zipSync, strToU8 } from 'fflate'
+import { signEntries, type PackEntry } from './sign'
+import { validateManifest } from '@mterminal/manifest-validator'
+
+const INCLUDED_DIRS = ['dist', 'themes']
+const INCLUDED_FILES = ['package.json', 'README.md', 'readme.md', 'icon.png']
+
+async function walk(root: string, prefix = ''): Promise<PackEntry[]> {
+  const out: PackEntry[] = []
+  let stat: { isDirectory(): boolean; isFile(): boolean }
+  try {
+    stat = await fs.stat(root)
+  } catch {
+    return out
+  }
+  if (!stat.isDirectory()) return out
+  const entries = await fs.readdir(root, { withFileTypes: true })
+  for (const e of entries) {
+    const abs = path.join(root, e.name)
+    const rel = prefix ? `${prefix}/${e.name}` : e.name
+    if (e.isDirectory()) {
+      out.push(...(await walk(abs, rel)))
+    } else if (e.isFile()) {
+      const content = await fs.readFile(abs)
+      out.push({ path: rel, content: new Uint8Array(content) })
+    }
+  }
+  return out
+}
+
+export interface PackOptions {
+  cwd: string
+  authorId: string
+  keyId: string
+  privKey: Uint8Array
+}
+
+export interface PackResult {
+  buf: Uint8Array
+  manifestId: string
+  version: string
+}
+
+export async function pack(opts: PackOptions): Promise<PackResult> {
+  const pkgPath = path.join(opts.cwd, 'package.json')
+  const raw = await fs.readFile(pkgPath, 'utf8')
+  const pkg = JSON.parse(raw) as Record<string, unknown>
+
+  const mt = (pkg.mterminal ?? {}) as Record<string, unknown>
+  const publisher = (mt.publisher ?? {}) as Record<string, unknown>
+  if (publisher.authorId !== opts.authorId || publisher.keyId !== opts.keyId) {
+    mt.publisher = { authorId: opts.authorId, keyId: opts.keyId }
+    pkg.mterminal = mt
+    await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  }
+
+  const validation = validateManifest(pkg)
+  if (!validation.ok) {
+    throw new Error(`manifest invalid:\n  - ${validation.errors.join('\n  - ')}`)
+  }
+
+  const entries: PackEntry[] = []
+  entries.push({
+    path: 'package.json',
+    content: new Uint8Array(await fs.readFile(pkgPath)),
+  })
+  for (const dir of INCLUDED_DIRS) {
+    entries.push(...(await walk(path.join(opts.cwd, dir), dir)))
+  }
+  for (const file of INCLUDED_FILES) {
+    if (file === 'package.json') continue
+    const abs = path.join(opts.cwd, file)
+    try {
+      const buf = await fs.readFile(abs)
+      entries.push({ path: file, content: new Uint8Array(buf) })
+    } catch {}
+  }
+
+  const sigB64 = await signEntries(entries, opts.privKey)
+  entries.push({ path: 'signature.sig', content: strToU8(sigB64) })
+
+  const zipMap: Record<string, Uint8Array> = {}
+  for (const e of entries) zipMap[e.path] = e.content
+  const buf = zipSync(zipMap)
+
+  return {
+    buf,
+    manifestId: validation.manifest.id,
+    version: validation.manifest.version,
+  }
+}

package/src/lib/sign.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+import { deterministicHashHex, generateKeyPair, signEntries, type PackEntry } from './sign'
+
+describe('deterministicHashHex', () => {
+  it('produces stable hash regardless of entry order', () => {
+    const a: PackEntry[] = [
+      { path: 'a.txt', content: new Uint8Array([1, 2, 3]) },
+      { path: 'b.txt', content: new Uint8Array([4, 5, 6]) },
+    ]
+    const b: PackEntry[] = [...a].reverse()
+    expect(deterministicHashHex(a)).toBe(deterministicHashHex(b))
+  })
+
+  it('excludes signature.sig from hash', () => {
+    const without: PackEntry[] = [{ path: 'a.txt', content: new Uint8Array([1]) }]
+    const withSig: PackEntry[] = [
+      ...without,
+      { path: 'signature.sig', content: new Uint8Array([99]) },
+    ]
+    expect(deterministicHashHex(without)).toBe(deterministicHashHex(withSig))
+  })
+})
+
+describe('signEntries / generateKeyPair', () => {
+  it('produces a 64-byte ed25519 signature', async () => {
+    const { priv } = await generateKeyPair()
+    const entries: PackEntry[] = [{ path: 'a.txt', content: new Uint8Array([1, 2]) }]
+    const sigB64 = await signEntries(entries, priv)
+    const sig = Buffer.from(sigB64, 'base64')
+    expect(sig.length).toBe(64)
+  })
+})

package/src/lib/sign.ts

@@ -0,0 +1,33 @@
+import * as ed from '@noble/ed25519'
+import { sha256, sha512 } from '@noble/hashes/sha2'
+import { bytesToHex } from '@noble/hashes/utils'
+
+ed.etc.sha512Sync = (...m: Uint8Array[]) => sha512(ed.etc.concatBytes(...m))
+
+export interface PackEntry {
+  path: string
+  content: Uint8Array
+}
+
+export function deterministicHashHex(entries: PackEntry[]): string {
+  const sorted = entries
+    .filter((e) => e.path !== 'signature.sig')
+    .map((e) => ({ path: e.path, hash: bytesToHex(sha256(e.content)) }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+
+  const lines = sorted.map((e) => `${e.path} ${e.hash}\n`).join('')
+  return bytesToHex(sha256(new TextEncoder().encode(lines)))
+}
+
+export async function signEntries(entries: PackEntry[], privKey: Uint8Array): Promise<string> {
+  const hashHex = deterministicHashHex(entries)
+  const message = new TextEncoder().encode(hashHex)
+  const sig = await ed.signAsync(message, privKey)
+  return Buffer.from(sig).toString('base64')
+}
+
+export async function generateKeyPair(): Promise<{ priv: Uint8Array; pubB64: string }> {
+  const priv = ed.utils.randomPrivateKey()
+  const pub = await ed.getPublicKeyAsync(priv)
+  return { priv, pubB64: Buffer.from(pub).toString('base64') }
+}

package/templates/minimal/README.md

@@ -0,0 +1,17 @@
+# EXT_ID
+
+An mTerminal extension scaffolded with `mtx init`.
+
+## develop
+
+```bash
+npm i
+npm run build
+```
+
+## publish
+
+```bash
+mtx pack
+mtx publish
+```

package/templates/minimal/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "mterminal-plugin-EXT_ID",
+  "version": "0.1.0",
+  "description": "an mTerminal extension",
+  "main": "dist/main.cjs",
+  "renderer": "dist/renderer.mjs",
+  "scripts": {
+    "build": "tsup"
+  },
+  "engines": {
+    "mterminal-api": "^1.0.0"
+  },
+  "mterminal": {
+    "id": "EXT_ID",
+    "displayName": "EXT_ID",
+    "category": "other",
+    "publisher": {
+      "authorId": "",
+      "keyId": ""
+    },
+    "activationEvents": ["onStartupFinished"],
+    "capabilities": [],
+    "contributes": {}
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  }
+}

package/templates/minimal/src/main.ts

@@ -0,0 +1,2 @@
+export function activate() {}
+export function deactivate() {}

package/templates/minimal/src/renderer.tsx

@@ -0,0 +1,2 @@
+export function activate() {}
+export function deactivate() {}

package/templates/minimal/tsup.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig([
+  {
+    entry: ['src/main.ts'],
+    format: ['cjs'],
+    outDir: 'dist',
+    outExtension: () => ({ js: '.cjs' }),
+    target: 'node22',
+    clean: true,
+  },
+  {
+    entry: ['src/renderer.tsx'],
+    format: ['esm'],
+    outDir: 'dist',
+    outExtension: () => ({ js: '.mjs' }),
+    target: 'es2022',
+  },
+])