@glyphteck/veyl 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# Veyl Headless
+
+`apps/headless` is the programmable Bun client for terminal users, scripts, automations, and MCP servers.
+
+It is a client, not a privileged backend. Headless accounts own their local machine credential, vault secret, wallet seed, and chat key material. The server should only create public account records, verify login challenges, and store encrypted vault material it cannot decrypt.
+
+The package also supports real passkey accounts from a terminal. Passkey create/login opens the configured Veyl web origin for the WebAuthn ceremony, receives a Firebase token on a localhost callback, then pairs a local machine credential to that signed-in account for future CLI sessions. True machine-created headless accounts remain separate from passkey-created accounts.
+
+## Interface Boundary
+
+`headless` is the client boundary. CLI, MCP, scripts, and future channel adapters are interfaces on top of the same client, not separate clients with their own account, vault, chat, or money logic.
+
+- `src/client.js`: shared programmable API.
+- `src/cli.js`: terminal command wrapper.
+- `src/mcp.js`: MCP wrapper.
+- `src/passkey.js`: browser-assisted passkey bridge for terminal flows.
+
+## API Shape
+
+The public surface should stay simple enough to infer from the command names:
+
+```js
+import { open } from '@glyphteck/veyl';
+
+const veyl = await open();
+
+const account = await veyl.account.create({ username: 'runner' });
+const vault = await veyl.vault.create();
+await veyl.vault.unlock();
+await veyl.chat.send('@alice', 'hello');
+const messages = await veyl.chat.read('@alice');
+
+await veyl.money.send('@alice', 1000);
+await veyl.money.request('@alice', 1000);
+const transactions = await veyl.money.transactions();
+
+console.log(account.uid, vault.vaultSecret, messages, transactions);
+```
+
+CLI names should mirror the JS API:
+
+```bash
+veyl create --passkey @runner
+veyl send @alice 1000
+veyl request @alice 1000
+veyl balance
+veyl read @alice
+veyl say @alice "hello"
+veyl listen
+
+veyl account create @runner
+veyl account create --passkey @runner
+veyl account login @runner
+veyl account login --passkey @runner
+veyl vault create
+veyl vault unlock
+veyl vault lock
+veyl chat read @alice
+veyl chat send @alice "hello"
+veyl money balance
+veyl money send @alice 1000
+veyl money request @alice 1000
+veyl transactions
+veyl mcp serve
+```
+
+The same commands are exposed as MCP tools through `veyl mcp serve`.
+
+`veyl listen` keeps one auth and vault session alive in the current process, then emits newline-delimited JSON events for new messages and wallet transfers. It is the terminal event-stream path for agents that do not want to speak MCP.
+
+Passkey browser auth defaults to `https://veyl.glyphteck.com`. Use `--web-url` or `VEYL_WEB_URL` to point the CLI at another allowed passkey origin, such as a local dev host or a future dedicated auth host.
+
+From this monorepo, use the root dev helper instead of the package filter form:
+
+```bash
+bun dev headless regtest create --passkey @runner
+```
+
+## Local Secrets
+
+The package creates a local profile under `~/.veyl` by default. It stores the machine credential and, unless `saveSecret: false` or `--no-save-secret` is used, the generated vault secret. Passkey flows pair and store a local machine credential by default so later CLI commands do not need a browser prompt; use `--no-save-credential` or `saveCredential: false` to return the credential material without saving the private key locally. Callers that already have a secret manager can pass `VEYL_HOME`, `VEYL_PROFILE`, `VEYL_VAULT_SECRET`, or explicit SDK options and store those secrets elsewhere.
+
+Glyphteck-owned Google Secret Manager bot seeds are not used by this public path.
+
+## Backend Contract
+
+The backend only verifies machine-key challenges and issues Firebase custom tokens:
+
+- `POST /headless/account/create/start`
+- `POST /headless/account/create/finish`
+- `POST /headless/account/login/start`
+- `POST /headless/account/login/finish`
+- `POST /headless/account/credential/add/start`
+- `POST /headless/account/credential/add/finish`
+
+Vault secrets, wallet entropy, chat seeds, Spark wallet boot, and message/payment signing all run locally in this package through shared Veyl primitives.
+
+Generic unlocked-account actions live in `@veyl/shared/account/actions`; this package only wraps them with headless account auth, local profile storage, CLI commands, and MCP serving.

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@glyphteck/veyl",
+    "version": "0.1.0",
+    "license": "Apache-2.0",
+    "type": "module",
+    "description": "Programmable Bun client for Veyl accounts, vaults, chat, and wallet payments.",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "bin": {
+        "veyl": "src/cli.js"
+    },
+    "files": [
+        "src",
+        "README.md",
+        "package.json"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "start": "bun src/cli.js",
+        "lint": "eslint . --quiet"
+    },
+    "dependencies": {
+        "@buildonspark/spark-sdk": "^0.8.8",
+        "@noble/hashes": "^2.2.0",
+        "@veyl/shared": "^0.1.0",
+        "firebase": "^12.15.0"
+    }
+}

package/src/cli.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+import { ClientNotReadyError, createClient } from './index.js';
+
+const HELP = `Usage:
+  veyl create [--passkey] @name
+  veyl login [--passkey] [@name]
+  veyl unlock
+  veyl send @name 1000
+  veyl request @name 1000
+  veyl balance
+  veyl read @name
+  veyl say @name "message"
+  veyl listen
+
+Structured:
+  veyl [--profile name] [--network REGTEST|MAINNET] account create @name
+  veyl account create --passkey @name
+  veyl account login @name
+  veyl account login --passkey [@name]
+  veyl account me
+  veyl vault create
+  veyl vault unlock [--secret value]
+  veyl vault lock
+  veyl chats
+  veyl chat read @name
+  veyl chat send @name "message"
+  veyl money balance
+  veyl money send @name 1000
+  veyl money request @name 1000
+  veyl money pay <request-id>
+  veyl transactions
+  veyl mcp serve
+
+Listen:
+  --interval ms        poll interval, minimum 1000
+  --replay            emit current messages and transactions on startup
+  --no-chats          skip chat message events
+  --no-transactions   skip transaction events
+
+Env:
+  VEYL_HOME           local profile directory
+  VEYL_PROFILE        default profile
+  VEYL_NETWORK        wallet network
+  VEYL_VAULT_SECRET   vault secret for unlock/create
+  VEYL_WEB_URL        passkey browser origin`;
+
+function print(value) {
+    if (value === undefined) {
+        return;
+    }
+    if (value === null) {
+        console.log('null');
+        return;
+    }
+    if (typeof value === 'string') {
+        console.log(value);
+        return;
+    }
+    console.log(JSON.stringify(value, null, 2));
+}
+
+function usageError(message) {
+    const error = new Error(`${message}\n\n${HELP}`);
+    error.code = 'usage';
+    return error;
+}
+
+function parseArgs(argv) {
+    const options = {};
+    const args = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const item = argv[index];
+        if (item === '--profile') {
+            options.profile = argv[++index];
+        } else if (item === '--network') {
+            options.network = argv[++index];
+        } else if (item === '--secret') {
+            options.secret = argv[++index];
+        } else if (item === '--no-save-secret') {
+            options.saveSecret = false;
+        } else if (item === '--passkey') {
+            options.passkey = true;
+        } else if (item === '--web-url') {
+            options.webUrl = argv[++index];
+        } else if (item === '--no-save-credential') {
+            options.saveCredential = false;
+        } else if (item === '--interval') {
+            options.interval = argv[++index];
+        } else if (item === '--chat-count') {
+            options.chatCount = argv[++index];
+        } else if (item === '--message-count') {
+            options.messageCount = argv[++index];
+        } else if (item === '--tx-count') {
+            options.txCount = argv[++index];
+        } else if (item === '--replay') {
+            options.replay = true;
+        } else if (item === '--no-chats') {
+            options.chats = false;
+        } else if (item === '--no-transactions') {
+            options.transactions = false;
+        } else {
+            args.push(item);
+        }
+    }
+    return { args, options };
+}
+
+async function runCommand(argv) {
+    const parsed = parseArgs(argv);
+    if (parsed.options.secret) {
+        process.env.VEYL_VAULT_SECRET = parsed.options.secret;
+    }
+    const [area, command, ...args] = parsed.args;
+    const veyl = createClient({
+        profile: parsed.options.profile,
+        network: parsed.options.network,
+    });
+
+    if (!area || area === 'help' || area === '--help' || area === '-h') {
+        return HELP;
+    }
+
+    if (area === 'chats') {
+        return veyl.chat.list();
+    }
+
+    if (area === 'transactions') {
+        return veyl.money.transactions();
+    }
+
+    if (area === 'create') {
+        return parsed.options.passkey
+            ? veyl.account.createPasskey({
+                username: args[0],
+                network: parsed.options.network,
+                webUrl: parsed.options.webUrl,
+                saveCredential: parsed.options.saveCredential,
+                onPasskeyUrl: (url) => console.error(`open ${url}`),
+            })
+            : veyl.account.create({ username: args[0], network: parsed.options.network, saveCredential: parsed.options.saveCredential });
+    }
+
+    if (area === 'login') {
+        return parsed.options.passkey
+            ? veyl.account.loginPasskey({
+                username: args[0],
+                network: parsed.options.network,
+                webUrl: parsed.options.webUrl,
+                saveCredential: parsed.options.saveCredential,
+                onPasskeyUrl: (url) => console.error(`open ${url}`),
+            })
+            : veyl.account.login({ username: args[0] });
+    }
+
+    if (area === 'me') {
+        return veyl.account.me();
+    }
+
+    if (area === 'unlock') {
+        return veyl.vault.unlock({ secret: parsed.options.secret, saveSecret: parsed.options.saveSecret });
+    }
+
+    if (area === 'lock') {
+        return veyl.vault.lock();
+    }
+
+    if (area === 'balance') {
+        return veyl.money.balance();
+    }
+
+    if (area === 'send') {
+        return veyl.money.send(args[0], args[1]);
+    }
+
+    if (area === 'request') {
+        return veyl.money.request(args[0], args[1]);
+    }
+
+    if (area === 'pay') {
+        return veyl.money.pay(args[0]);
+    }
+
+    if (area === 'txs') {
+        return veyl.money.transactions();
+    }
+
+    if (area === 'read') {
+        return veyl.chat.read(args[0]);
+    }
+
+    if (area === 'say' || area === 'msg') {
+        return veyl.chat.send(args[0], args.slice(1).join(' '));
+    }
+
+    if (area === 'listen') {
+        const controller = new AbortController();
+        process.once('SIGINT', () => controller.abort());
+        process.once('SIGTERM', () => controller.abort());
+        await veyl.listen({
+            interval: parsed.options.interval,
+            chatCount: parsed.options.chatCount,
+            messageCount: parsed.options.messageCount,
+            txCount: parsed.options.txCount,
+            replay: parsed.options.replay,
+            chats: parsed.options.chats,
+            transactions: parsed.options.transactions,
+            signal: controller.signal,
+            onEvent: (event) => console.log(JSON.stringify(event)),
+        });
+        return undefined;
+    }
+
+    if (area === 'account') {
+        const passkeyOptions = {
+            username: args[0],
+            network: parsed.options.network,
+            webUrl: parsed.options.webUrl,
+            saveCredential: parsed.options.saveCredential,
+            onPasskeyUrl: (url) => console.error(`open ${url}`),
+        };
+        if (command === 'create') {
+            return parsed.options.passkey
+                ? veyl.account.createPasskey(passkeyOptions)
+                : veyl.account.create({ username: args[0], network: parsed.options.network, saveCredential: parsed.options.saveCredential });
+        }
+        if (command === 'login') {
+            return parsed.options.passkey
+                ? veyl.account.loginPasskey(passkeyOptions)
+                : veyl.account.login({ username: args[0] });
+        }
+        if (command === 'me') return veyl.account.me();
+        throw usageError('unknown account command');
+    }
+
+    if (area === 'vault') {
+        if (command === 'create') return veyl.vault.create({ secret: parsed.options.secret, saveSecret: parsed.options.saveSecret });
+        if (command === 'unlock') return veyl.vault.unlock({ secret: parsed.options.secret, saveSecret: parsed.options.saveSecret });
+        if (command === 'lock') return veyl.vault.lock();
+        throw usageError('unknown vault command');
+    }
+
+    if (area === 'chat') {
+        if (command === 'list') return veyl.chat.list();
+        if (command === 'read') return veyl.chat.read(args[0]);
+        if (command === 'send') return veyl.chat.send(args[0], args.slice(1).join(' '));
+        throw usageError('unknown chat command');
+    }
+
+    if (area === 'money') {
+        if (command === 'balance') return veyl.money.balance();
+        if (command === 'send') return veyl.money.send(args[0], args[1]);
+        if (command === 'request') return veyl.money.request(args[0], args[1]);
+        if (command === 'pay') return veyl.money.pay(args[0]);
+        if (command === 'transactions') return veyl.money.transactions();
+        throw usageError('unknown money command');
+    }
+
+    if (area === 'mcp') {
+        if (command === 'serve') return veyl.mcp.serve();
+        throw usageError('unknown mcp command');
+    }
+
+    throw usageError('unknown command');
+}
+
+async function main() {
+    try {
+        print(await runCommand(process.argv.slice(2)));
+    } catch (error) {
+        if (error instanceof ClientNotReadyError) {
+            console.error(error.message);
+            process.exitCode = 2;
+            return;
+        }
+        console.error(error?.message || String(error));
+        process.exitCode = error?.code === 'usage' ? 1 : 2;
+    }
+}
+
+main();