@helios-lang/contract-utils 0.3.22 → 0.3.24

package/README.md

@@ -26,7 +26,16 @@ Credentials are stored in a versioned `debugger.json` file:
 
 Set `HELIOS_CONFIG_HOME` to override the directory. Unix directories/files use modes 700/600. Windows uses a current-user-only ACL. The JSON has `{version:1,selected,profiles}`, where `selected` is a project ID and `profiles` maps project IDs to `{id,name,created_at,apiKey,wallet,endpoint}`. Names need not be unique. Re-running login refreshes that wallet's snapshot and removes revoked projects while preserving other wallets. It keeps the selected project when available and otherwise selects the oldest returned project. No signatures, browser session cookies, or temporary login tokens are persisted.
 
-API keys in this file are secrets: do not commit or share it. They authorize both capture uploads and reads for their project. Login never prints key values. The console's ordinary metadata endpoints do not return them; key recovery uses an explicitly approved, short-lived CLI request.
+Project API keys can be shared with collaborators. They authorize capture uploads and reads for their project. The project page in the Console always displays its key in a yellow box.
+
+To import a key from another project owner without wallet login:
+
+```sh
+helios import-key hdbg_<key-from-project-page>
+helios compile --project "Shared project" --help
+```
+
+Import validates the key, resolves the project name automatically, and merges it into the same configuration used by compilation and VS Code. Reimporting updates that project without duplicating it or removing other projects. Wallet login preserves imported projects belonging to other wallets.
 
 For development, run `pnpm test`. `node scripts/check-global-cli.mjs` packs the package, installs it into an isolated npm global prefix, and checks executable discovery and equivalent compilation. The CLI portability workflow runs these checks on Windows, macOS, and Linux with Node 22 and 24. Publish the package only after the website and Worker with CLI-login support have been deployed.
 
@@ -46,3 +55,9 @@ Generated JS/TS exports `$debugger: {projectId,name,apiKey,endpoint,sources}` an
 With the corresponding tx-utils release and ledger evaluation-observer support, `spendWithRedeemer()`, minting/staking methods, and attached programs automatically deliver failed builds to that project. No explicit `makeDebuggerService()` call is needed. `makeTxBuilder({isMainnet, debugger:false})` disables automatic capture; an explicit debugger service overrides bundle configuration. Unannotated bundles retain their existing behavior.
 
 The API key is intentionally embedded in generated bundles, including browser bundles, and grants upload **and read** access to that project's feed. Use project-specific keys appropriate for that distribution. The key is sent in the authorization header, not in capture payloads. Omitting `--project` embeds no debugger credentials.
+
+### Offline wallet generation
+
+`helios wallet create --network preprod` prints JSON containing a cryptographically random 24-word recovery phrase and its base address. It does not contact a service. Supported networks are `preprod` (default), `preview`, and `mainnet`.
+
+Use `helios wallet create --network preprod --out wallet.json` to write a new private file instead of printing the phrase. Existing files are never overwritten. The output phrase can be pasted into a demo’s ignored `.env.local` file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helios-lang/contract-utils",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "description": "Convenience and type-safety utilities for using Helios validators from within Typescript",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -42,6 +42,7 @@
     "@helios-lang/compiler-utils": "^0.5.15",
     "@helios-lang/crypto": "0.2.3",
     "@helios-lang/ledger": "^0.7.8",
+    "@helios-lang/tx-utils": "^0.6.41",
     "@helios-lang/type-utils": "^0.3.0",
     "@helios-lang/uplc": "^0.7.15",
     "open": "^10.2.0"

package/src/cli/config.mjs

@@ -13,7 +13,7 @@ import { randomUUID } from "node:crypto"
 import { execFile } from "node:child_process"
 import { promisify } from "node:util"
 const exec = promisify(execFile)
-async function windowsAcl(path, directory, set = false) {
+export async function windowsAcl(path, directory, set = false) {
     // Pass paths through the environment, never interpolate them into PowerShell.
     const script = `
 $ErrorActionPreference = 'Stop'
@@ -102,11 +102,47 @@ export async function installProjects(
     endpoint,
     path = configPath()
 ) {
+    if (!/^[a-f0-9]{56}$/.test(wallet))
+        throw new Error("Invalid wallet response")
+    validateProjects(projects)
+    const data = await readConfig(path)
+    for (const [id, profile] of Object.entries(data.profiles))
+        if (profile.wallet === wallet && profile.endpoint === endpoint)
+            delete data.profiles[id]
+    for (const project of projects)
+        data.profiles[project.id] = { ...project, wallet, endpoint }
+    if (!data.profiles[data.selected])
+        data.selected = [...projects].sort(
+            (a, b) => a.created_at - b.created_at || a.id.localeCompare(b.id)
+        )[0].id
+    return writeConfig(data, path)
+}
+export async function installSharedProject(
+    project,
+    endpoint,
+    path = configPath()
+) {
+    validateProjects([project])
+    const data = await readConfig(path)
+    const previous = data.profiles[project.id]
+    if (previous && previous.endpoint !== endpoint)
+        throw new Error(
+            "Project ID already exists for another debugger service"
+        )
     if (
-        !/^[a-f0-9]{56}$/.test(wallet) ||
-        !Array.isArray(projects) ||
-        !projects.length
+        previous &&
+        previous.apiKey === project.apiKey &&
+        previous.name === project.name &&
+        previous.created_at === project.created_at
     )
+        return { path, alreadyExists: true }
+    data.profiles[project.id] = { ...previous, ...project, endpoint }
+    if (!data.profiles[data.selected]) data.selected = project.id
+    await writeConfig(data, path)
+    return { path, alreadyExists: false }
+}
+function validateProjects(projects) {
+    if (!Array.isArray(projects) || !projects.length)
         throw new Error("Invalid or empty project response")
     const ids = new Set()
     for (const p of projects) {
@@ -122,16 +158,8 @@ export async function installProjects(
             throw new Error("Invalid project response")
         ids.add(p.id)
     }
-    const data = await readConfig(path)
-    for (const [id, profile] of Object.entries(data.profiles))
-        if (profile.wallet === wallet && profile.endpoint === endpoint)
-            delete data.profiles[id]
-    for (const project of projects)
-        data.profiles[project.id] = { ...project, wallet, endpoint }
-    if (!data.profiles[data.selected])
-        data.selected = [...projects].sort(
-            (a, b) => a.created_at - b.created_at || a.id.localeCompare(b.id)
-        )[0].id
+}
+async function writeConfig(data, path) {
     const dir = dirname(path)
     const existed = await inspect(dir, true)
     await mkdir(dir, { recursive: true, mode: 0o700 })

package/src/cli/import-key.mjs

@@ -0,0 +1,56 @@
+import { installSharedProject } from "./config.mjs"
+
+export async function importKey(
+    apiKey,
+    {
+        endpoint = "https://debugger.helios-lang.io",
+        fetchImpl = fetch,
+        save = installSharedProject,
+        log = console.log
+    } = {}
+) {
+    if (typeof apiKey !== "string" || !/^hdbg_[a-f0-9]{64}$/.test(apiKey))
+        throw new Error(
+            "Invalid debugger API key. Copy the full key from the project's Console page."
+        )
+    const origin = new URL(endpoint)
+    if (
+        origin.protocol !== "https:" ||
+        origin.username ||
+        origin.password ||
+        origin.pathname !== "/" ||
+        origin.search ||
+        origin.hash
+    )
+        throw new Error("Debugger endpoint must be an HTTPS origin")
+    let response
+    try {
+        response = await fetchImpl(origin.origin + "/v1/project", {
+            headers: { Authorization: `Bearer ${apiKey}` },
+            redirect: "error",
+            signal: AbortSignal.timeout(10000)
+        })
+    } catch {
+        throw new Error(
+            "Could not reach the debugger service. Check your connection and try again."
+        )
+    }
+    if (response.status === 401)
+        throw new Error(
+            "This debugger API key is invalid or revoked. Ask the project owner for an active key."
+        )
+    if (!response.ok)
+        throw new Error(
+            `Debugger project lookup failed (HTTP ${response.status}). Try again later.`
+        )
+    const { id, name, created_at } = await response.json()
+    const { path, alreadyExists } = await save(
+        { id, name, created_at, apiKey },
+        origin.origin
+    )
+    if (alreadyExists) log("Key already exists")
+    else
+        log(`Imported project ${JSON.stringify(name)} into ${path}.
+Compile with helios compile --project ${JSON.stringify(name)} (or hl2ts --project ${JSON.stringify(name)}).`)
+    return { id, name, created_at }
+}

package/src/cli/wallet-file.mjs

@@ -0,0 +1,14 @@
+import { open, unlink } from "node:fs/promises"
+import { windowsAcl } from "./config.mjs"
+export async function writePrivateWallet(path, json) {
+    const file = await open(path, "wx", 0o600)
+    try {
+        if (process.platform === "win32") await windowsAcl(path, false, true)
+        await file.writeFile(json, "utf8")
+    } catch (error) {
+        await file.close()
+        await unlink(path)
+        throw error
+    }
+    await file.close()
+}

package/src/cli/wallet.mjs

@@ -0,0 +1,51 @@
+import { randomBytes } from "node:crypto"
+import { parseArgs } from "node:util"
+import { makeRootPrivateKey } from "@helios-lang/tx-utils"
+import { makeShelleyAddress } from "@helios-lang/ledger"
+
+export function createWallet(network = "preprod") {
+    if (!["preprod", "preview", "mainnet"].includes(network))
+        throw new Error("Network must be preprod, preview, or mainnet")
+    const key = makeRootPrivateKey([...randomBytes(32)])
+    const address = makeShelleyAddress(
+        network === "mainnet",
+        key.deriveSpendingKey().derivePubKey().hash(),
+        key.deriveStakingKey().derivePubKey().hash()
+    )
+    return {
+        network,
+        phrase: key.toPhrase().join(" "),
+        address: address.toBech32()
+    }
+}
+export async function walletCommand(args) {
+    const [command, ...rest] = args
+    if (["--help", "-h", "help"].includes(command)) {
+        console.log(
+            "helios wallet create [--network preprod|preview|mainnet] [--out wallet.json]\nGenerates a 24-word recovery phrase and address offline. Without --out, prints the secret phrase as JSON. --out creates a new owner-only file and never overwrites an existing file."
+        )
+        return
+    }
+    if (command !== "create")
+        throw new Error(
+            "Usage: helios wallet create [--network preprod|preview|mainnet] [--out wallet.json]"
+        )
+    const { values } = parseArgs({
+        args: rest,
+        options: {
+            network: { type: "string", default: "preprod" },
+            out: { type: "string" }
+        }
+    })
+    const wallet = createWallet(values.network)
+    const json = JSON.stringify(wallet, null, 2) + "\n"
+    if (values.out !== undefined) {
+        if (!values.out.trim()) throw new Error("--out requires a file path")
+        // Reuse credential-file ACL protection on Windows, before storing secrets.
+        const { writePrivateWallet } = await import("./wallet-file.mjs")
+        await writePrivateWallet(values.out, json)
+        console.log(
+            `Created ${wallet.network} wallet: ${wallet.address}\nRecovery phrase saved in ${values.out}`
+        )
+    } else console.log(json)
+}

package/src/helios.mjs

@@ -7,6 +7,14 @@ try {
         await compile(
             args.map((arg) => (["--help", "-h"].includes(arg) ? "help" : arg))
         )
+    } else if (command === "wallet") {
+        const { walletCommand } = await import("./cli/wallet.mjs")
+        await walletCommand(args)
+    } else if (command === "import-key") {
+        if (args.length !== 1)
+            throw new Error("Usage: helios import-key <api-key>")
+        const { importKey } = await import("./cli/import-key.mjs")
+        await importKey(args[0])
     } else if (command === "login") {
         if (args.some((arg) => arg !== "--no-browser"))
             throw new Error("Usage: helios login [--no-browser]")
@@ -38,7 +46,7 @@ try {
         )
     } else if (!command || ["--help", "-h", "help"].includes(command)) {
         console.log(
-            "Helios CLI\n\n  helios compile [options]  Compile contracts (same options as hl2ts)\n  helios login [--no-browser]  Install project API keys through the Console\n  helios --version"
+            "Helios CLI\n\n  helios compile [options]  Compile contracts (same options as hl2ts)\n  helios login [--no-browser]  Install project API keys through the Console\n  helios import-key <api-key>  Install a shared project API key\n  helios wallet create [--network preprod] [--out wallet.json]  Generate a wallet offline\n  helios --version"
         )
     } else throw new Error(`Unknown command: ${command}. Run helios --help.`)
 } catch (error) {

package/types/cli/config.d.mts

@@ -1,4 +1,9 @@
+export function windowsAcl(path: any, directory: any, set?: boolean): Promise<void>;
 export function configPath(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string;
 export function readConfig(path?: string): Promise<any>;
-export function installProjects(wallet: any, projects: any, endpoint: any, path?: string): Promise<string>;
+export function installProjects(wallet: any, projects: any, endpoint: any, path?: string): Promise<any>;
+export function installSharedProject(project: any, endpoint: any, path?: string): Promise<{
+    path: string;
+    alreadyExists: boolean;
+}>;
 //# sourceMappingURL=config.d.mts.map

package/types/cli/config.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.mts","sourceRoot":"","sources":["../../src/cli/config.mjs"],"names":[],"mappings":"AAiDA,uGAcC;AAqBD,wDAaC;AACD,2GA2DC"}
+{"version":3,"file":"config.d.mts","sourceRoot":"","sources":["../../src/cli/config.mjs"],"names":[],"mappings":"AAeA,oFAiCC;AACD,uGAcC;AAqBD,wDAaC;AACD,wGAoBC;AACD;;;GAuBC"}