@gfp/cli
v0.1.0-beta.1
Published
Scaffold, develop and run gfp secret-channel apps: gfp new, gfp dev, gfp run, gfp keygen
Readme
@gfp/cli
Build apps on a gfp secret channel. One key file is both the channel's address and its credential. A
page (a PWA installed on the channel's own origin, https://<label>.gfp.pmita.org/) and a
producer (a Node process on a machine you trust) exchange end-to-end encrypted messages through
a relay that cannot read them. The producer also serves the page to browsers over the channel, so
there is nothing to deploy to a web host.
Quickstart
npx @gfp/cli new myapp
cd myapp
npm install
npm run devnpm run dev (gfp dev) starts a local relay and the bootstrap site, builds the page and
rebuilds it on change, runs producer.ts (restarting it when its code changes), and prints a URL
and a dev key. Open the URL, paste the key, and the page installs. The dev key lives in
.gfp/dev.chankey; it only works with the local relay. Requires Node 24 or newer.
The app
| File | What it is |
| --------------------- | --------------------------------------------------------------------------- |
| src/protocol.ts | The messages, shared by both sides: message("myapp/say", s.object({...})) |
| src/main.ts | The page: const ch = await connect(), then ch.on, ch.send |
| producer.ts | export default defineProducer({ app: "./dist", handlers: [...] }) |
| public/gfp-app.json | Name, version and icons; bump version so installed pages update |
| rspack.config.mjs | defineGfpApp() from @gfp/build: CSP-safe, hashed output in dist |
The pattern: define each message once in protocol.ts with a schema, so both sides validate
the same thing. The page sends (ch.send, or ch.request(Say, data, Reversed) to wait for the
answer); the producer answers with handle(Say, (data, ctx) => ctx.reply(Reversed, ...)). Prefix
message types with your app's name. See
@gfp/app for the API.
producer.ts runs directly on Node's built-in TypeScript type stripping, so imports name the
.ts file (./src/protocol.ts) and only erasable syntax is allowed (no enums or namespaces).
npx tsc --noEmit checks both sides.
Run it for real
npx gfp keygen --domain dev.gfp.pmita.org # writes <label>.chankey (mode 0600)
npm run build
npx gfp run producer.ts --key <label>.chankey # or: npm start -- --key <label>.chankeyOpen the channel URL that keygen printed and import the key file there (file picker, drag and
drop, or paste). The relay is found through https://<key host>/config.json; --relay <wss url>
overrides it. --watch re-serves dist/ when it changes. Run the producer on any machine you
trust with the key: a laptop, a Raspberry Pi, a VPS.
Commands
| Command | What it does |
| ---------------------------------------------------------- | --------------------------------------------------------- |
| gfp new <dir> | Create an app in a new or empty directory |
| gfp dev [--port <n>] | Local relay + bootstrap + rebuilds + producer (port 5280) |
| gfp run <producer.ts> --key <file> [--relay] [--watch] | Run a producer on the key's channel until Ctrl-C |
| gfp keygen --domain <domain> [--out <path>] [--note <t>] | Write a new key file |
Security model
- The key file is the credential. Anyone holding it can read and send on the channel and serve its app. Deliver it out of band, delete it after importing, and never commit it.
- Producers are trusted. A producer holds the key and the app it serves runs with full access to the channel's origin. Only run producers you trust, on machines you trust.
- The relay is untrusted. It sees ciphertext, sizes and timing, never message contents; it can drop, delay or replay messages.
- Handlers must be idempotent. The relay keeps five minutes of messages and may redeliver them, and a restarted producer sees that window again.
- Never put a key in a URL (or a query string or fragment): URLs end up in history, logs and sync. Use the file picker, drag and drop, or paste.
License
MIT
