@airfone/connector 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AirFone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @airfone/connector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Types and the `airfone` command line tool for building, testing, packing and publishing AirFone
+connectors. Actions run locally in the same QuickJS sandbox as AirFone, so what passes here passes
+in review.
+
+## Install
+
+```sh
+npm install --save-dev @airfone/connector
+npx airfone --help
+```
+
+## Commands
+
+```
+airfone connector dev <action>   run one action against the real API, in the AirFone sandbox
+airfone connector test           validate manifest.json and run the review checks and fixtures
+airfone connector pack           write dist/<id>-<version>.tar and print its sha256
+airfone connector sign [FILE]    print the signature for a packed bundle
+airfone connector keygen         create your Ed25519 signing key
+airfone connector publish        test, pack, sign and upload (needs AIRFONE_TOKEN)
+airfone knowledge push|delete|sources
+```
+
+Limits match AirFone: 64 MB memory, 2 s CPU and 10 s wall time per action.
+
+## Types
+
+```ts
+import { defineActions } from '@airfone/connector';
+
+export const actions = defineActions({
+  async lookup(ctx, input) {
+    return { ok: true };
+  },
+});
+```
+
+Full guide: https://developers.airfone.app/docs/connectors/
+
+## License
+
+MIT

package/dist/bundle.d.ts

@@ -0,0 +1,20 @@
+import { type KeyObject } from 'node:crypto';
+export declare const MAX_BUNDLE_BYTES: number;
+export declare const MAX_JS_BYTES: number;
+export declare const sha256Hex: (b: Uint8Array) => string;
+export declare const signingMessage: (id: string, version: string, sha256: string) => Buffer<ArrayBuffer>;
+/** Packs files into a deterministic tar: manifest.json, index.js, then ui/ sorted. */
+export declare function pack(manifestJson: Uint8Array, js: string | null, ui: Map<string, Uint8Array>): Buffer;
+/** Reads a connector directory: manifest.json, index.js (if present) and every file under ui/. */
+export declare function readProject(dir: string): {
+    manifestText: string;
+    js: string | null;
+    ui: Map<string, Uint8Array<ArrayBufferLike>>;
+};
+export declare function defaultKeyPath(): string;
+/** Creates an Ed25519 key in PKCS#8 PEM, readable only by you. */
+export declare function keygen(path: string, force?: boolean): string;
+export declare function loadKey(path: string): KeyObject;
+/** The raw 32-byte public key, base64. This is what you register in the console. */
+export declare function publicKeyBase64(key: KeyObject): string;
+export declare function signBundle(key: KeyObject, id: string, version: string, sha256: string): string;

package/dist/bundle.js

@@ -0,0 +1,101 @@
+// Bundles and signatures, as bundle.rs defines them.
+//
+// A bundle is a tar of manifest.json, an optional index.js and optional ui/
+// files, addressed by the sha256 of the tar bytes. The developer signs
+// "airfone-connector-v1\n{id}\n{version}\n{sha256}" with Ed25519.
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign as edSign } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, sep } from 'node:path';
+export const MAX_BUNDLE_BYTES = 5 * 1024 * 1024;
+export const MAX_JS_BYTES = 1024 * 1024;
+export const sha256Hex = (b) => createHash('sha256').update(b).digest('hex');
+export const signingMessage = (id, version, sha256) => Buffer.from(`airfone-connector-v1\n${id}\n${version}\n${sha256}`);
+function octal(n, width) { return n.toString(8).padStart(width - 1, '0') + '\0'; }
+/** One GNU tar header, as the tar crate's Header::new_gnu writes it. */
+function header(path, size) {
+    const h = Buffer.alloc(512, 0);
+    if (Buffer.byteLength(path) > 99)
+        throw new Error(`path too long for the bundle: ${path}`);
+    h.write(path, 0, 'utf8');
+    h.write(octal(0o644, 8), 100, 'ascii');
+    h.write(octal(0, 8), 108, 'ascii');
+    h.write(octal(0, 8), 116, 'ascii');
+    h.write(octal(size, 12), 124, 'ascii');
+    h.write(octal(0, 12), 136, 'ascii');
+    h.write('        ', 148, 'ascii');
+    h.write('0', 156, 'ascii');
+    h.write('ustar ', 257, 'ascii');
+    h.write(' \0', 263, 'ascii');
+    let sum = 0;
+    for (const b of h)
+        sum += b;
+    h.write(sum.toString(8).padStart(6, '0') + '\0 ', 148, 'ascii');
+    return h;
+}
+/** Packs files into a deterministic tar: manifest.json, index.js, then ui/ sorted. */
+export function pack(manifestJson, js, ui) {
+    const parts = [];
+    const add = (path, data) => {
+        parts.push(header(path, data.length), Buffer.from(data));
+        const pad = (512 - (data.length % 512)) % 512;
+        if (pad)
+            parts.push(Buffer.alloc(pad, 0));
+    };
+    add('manifest.json', manifestJson);
+    if (js !== null)
+        add('index.js', Buffer.from(js, 'utf8'));
+    for (const p of [...ui.keys()].sort((a, b) => (Buffer.from(a) < Buffer.from(b) ? -1 : a === b ? 0 : 1)))
+        add(p, ui.get(p));
+    parts.push(Buffer.alloc(1024, 0));
+    return Buffer.concat(parts);
+}
+/** Reads a connector directory: manifest.json, index.js (if present) and every file under ui/. */
+export function readProject(dir) {
+    const manifestPath = join(dir, 'manifest.json');
+    if (!existsSync(manifestPath))
+        throw new Error(`no manifest.json in ${dir}`);
+    const manifestText = readFileSync(manifestPath, 'utf8');
+    const jsPath = join(dir, 'index.js');
+    const js = existsSync(jsPath) ? readFileSync(jsPath, 'utf8') : null;
+    const ui = new Map();
+    const uiDir = join(dir, 'ui');
+    const walk = (d) => {
+        for (const name of readdirSync(d)) {
+            const full = join(d, name);
+            if (statSync(full).isDirectory())
+                walk(full);
+            else
+                ui.set(relative(dir, full).split(sep).join('/'), readFileSync(full));
+        }
+    };
+    if (existsSync(uiDir))
+        walk(uiDir);
+    return { manifestText, js, ui };
+}
+export function defaultKeyPath() {
+    return process.env.AIRFONE_SIGNING_KEY ?? join(homedir(), '.airfone', 'connector-signing-key.pem');
+}
+/** Creates an Ed25519 key in PKCS#8 PEM, readable only by you. */
+export function keygen(path, force = false) {
+    if (existsSync(path) && !force)
+        throw new Error(`${path} already exists. Pass --force to replace it.`);
+    const { privateKey } = generateKeyPairSync('ed25519');
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return publicKeyBase64(privateKey);
+}
+export function loadKey(path) {
+    if (!existsSync(path))
+        throw new Error(`no signing key at ${path}. Run: airfone connector keygen`);
+    return createPrivateKey(readFileSync(path));
+}
+/** The raw 32-byte public key, base64. This is what you register in the console. */
+export function publicKeyBase64(key) {
+    const der = createPublicKey(key).export({ type: 'spki', format: 'der' });
+    return Buffer.from(der.subarray(der.length - 32)).toString('base64');
+}
+export function signBundle(key, id, version, sha256) {
+    return edSign(null, signingMessage(id, version, sha256), key).toString('base64');
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { type Canonical } from './manifest.js';
+export type { Canonical };

package/dist/cli.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+// airfone connector dev|test|pack|sign|keygen|publish
+// airfone knowledge push|delete|sources (see ./knowledge.ts)
+import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { defaultKeyPath, keygen, loadKey, MAX_BUNDLE_BYTES, pack, publicKeyBase64, readProject, sha256Hex, signBundle } from './bundle.js';
+import { LocalHost } from './host.js';
+import { runHttp } from './http.js';
+import { checkSchema, parseManifest, withConfigDefaults } from './manifest.js';
+import { fixtures, review } from './review.js';
+import { runAction, stopHttpWorker } from './runner.js';
+import { knowledge } from './knowledge.js';
+const HELP = `airfone connector <command> [options]
+
+Commands
+  dev <action>   Run one action against the real API, in the same sandbox as AirFone.
+                   --input '{"q":"rice"}' or --input @input.json
+                   --config FILE    install settings (default .airfone/config.json)
+                   --secrets FILE   secrets by name (default .airfone/secrets.json)
+                   --allow-local    allow http:// and private addresses, for a mock server
+                   --watch          run again when files change
+  test           Validate manifest.json and run AirFone's review checks and every fixture
+                 (manifest fixtures and tests/*.json). No network, as in review.
+  pack           Write dist/<id>-<version>.tar and print its sha256.
+  sign [FILE]    Print the signature for a packed bundle, for uploading in the console.
+  keygen         Create your Ed25519 signing key and print the public key to register.
+  publish        test, pack, sign and upload. Needs AIRFONE_TOKEN (an access token for your
+                 AirFone account) and AIRFONE_API (default https://app.airfone.app).
+
+Options for every command
+  --dir DIR      the connector folder (default: current folder)
+  --key FILE     signing key (default ~/.airfone/connector-signing-key.pem or AIRFONE_SIGNING_KEY)
+
+Limits match AirFone: 64 MB memory, 2 s CPU and 10 s wall time per action.`;
+function parseArgs(argv) {
+    const pos = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const [k, v] = a.slice(2).split('=', 2);
+            if (v !== undefined)
+                flags[k] = v;
+            else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--') && !['watch', 'allow-local', 'force', 'help'].includes(k))
+                flags[k] = argv[++i];
+            else
+                flags[k] = true;
+        }
+        else
+            pos.push(a);
+    }
+    return { pos, flags };
+}
+const out = (s) => process.stdout.write(s + '\n');
+const err = (s) => process.stderr.write(s + '\n');
+function readJson(path, fallback) {
+    if (!existsSync(path))
+        return fallback;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`${path}: ${e.message}`);
+    }
+}
+function load(dir) {
+    const p = readProject(dir);
+    const m = parseManifest(p.manifestText);
+    if (m.actions.some((a) => a.kind === 'js') && p.js === null)
+        throw new Error('the manifest has JS actions but there is no index.js');
+    return { ...p, m };
+}
+function printFindings(findings) {
+    if (findings.length === 0) {
+        out('All checks passed.');
+        return;
+    }
+    for (const f of findings)
+        out(`${f.level === 'error' ? 'Failed ' : 'Warning'}  ${f.message}`);
+}
+async function dev(dir, pos, flags) {
+    const once = async () => {
+        const { m, js } = load(dir);
+        const name = pos[0];
+        if (!name) {
+            out('Actions:');
+            for (const a of m.actions)
+                out(`  ${a.name}  (${a.kind}, ${a.risk})  ${a.description}`);
+            return true;
+        }
+        const action = m.actions.find((a) => a.name === name);
+        if (!action)
+            throw new Error(`no action named ${name}. Run without an action to list them.`);
+        const raw = typeof flags.input === 'string' ? flags.input : '{}';
+        const input = raw.startsWith('@') ? JSON.parse(readFileSync(resolve(dir, raw.slice(1)), 'utf8')) : JSON.parse(raw);
+        const config = withConfigDefaults(m.config, readJson(resolve(dir, typeof flags.config === 'string' ? flags.config : '.airfone/config.json'), {}));
+        const secrets = readJson(resolve(dir, typeof flags.secrets === 'string' ? flags.secrets : '.airfone/secrets.json'), {});
+        checkSchema('config', m.config, config);
+        checkSchema('input', action.input, input);
+        const egress = { allowLocal: flags['allow-local'] === true };
+        const started = Date.now();
+        let result;
+        if (action.kind === 'http')
+            result = await runHttp(m, action, input, config, secrets, egress);
+        else
+            result = await runAction(js, action.js ?? action.name, input, config, new LocalHost(m, config, secrets, join(dir, '.airfone', 'store.json'), egress, (l) => err(`  ${l}`)));
+        out(JSON.stringify(result, null, 2));
+        try {
+            checkSchema('output', action.output, result);
+        }
+        catch (e) {
+            err(`Warning  ${e.message}`);
+        }
+        err(`done in ${Date.now() - started} ms`);
+        return true;
+    };
+    const guarded = async () => { try {
+        await once();
+        return true;
+    }
+    catch (e) {
+        err(`Error  ${e.message}`);
+        return false;
+    } };
+    const ok = await guarded();
+    if (flags.watch !== true) {
+        stopHttpWorker();
+        return ok;
+    }
+    err('Watching for changes. Press Ctrl+C to stop.');
+    let timer;
+    watch(dir, { recursive: true }, (_e, file) => {
+        if (!file || String(file).startsWith('.airfone') || String(file).startsWith('dist') || String(file).includes('node_modules'))
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => { err(`\n${file} changed`); void guarded(); }, 150);
+    });
+    return new Promise(() => { });
+}
+async function test(dir) {
+    const { m, js } = load(dir);
+    const list = fixtures(m, dir);
+    out(`${m.id}@${m.version}: ${m.actions.length} action(s), ${list.length} fixture(s)`);
+    const findings = await review(m, js, list);
+    printFindings(findings);
+    return !findings.some((f) => f.level === 'error');
+}
+function packTo(dir, flags) {
+    const { m, js, ui, manifestText } = load(dir);
+    const tar = pack(Buffer.from(manifestText), js, ui);
+    if (tar.length > MAX_BUNDLE_BYTES)
+        throw new Error(`the bundle is ${tar.length} bytes; the limit is ${MAX_BUNDLE_BYTES}`);
+    const outDir = resolve(dir, typeof flags.out === 'string' ? flags.out : 'dist');
+    mkdirSync(outDir, { recursive: true });
+    const file = join(outDir, `${m.id}-${m.version}.tar`);
+    writeFileSync(file, tar);
+    return { m, tar, file, sha256: sha256Hex(tar) };
+}
+async function publish(dir, flags) {
+    const token = process.env.AIRFONE_TOKEN;
+    if (!token)
+        throw new Error('set AIRFONE_TOKEN to an access token for your AirFone account');
+    const api = (process.env.AIRFONE_API ?? 'https://app.airfone.app').replace(/\/$/, '');
+    if (!(await test(dir)))
+        throw new Error('fix the failed checks first; AirFone would reject this version');
+    const { m, tar, file, sha256 } = packTo(dir, flags);
+    const key = loadKey(typeof flags.key === 'string' ? flags.key : defaultKeyPath());
+    const signature = signBundle(key, m.id, m.version, sha256);
+    out(`Uploading ${basename(file)} (${tar.length} bytes, sha256 ${sha256})`);
+    const form = new FormData();
+    form.append('bundle', new Blob([tar], { type: 'application/x-tar' }), basename(file));
+    form.append('signature', signature);
+    const r = await fetch(`${api}/api/developer/connectors/${encodeURIComponent(m.id)}/versions`, {
+        method: 'POST', headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' }, body: form,
+    });
+    const text = await r.text();
+    let body = null;
+    try {
+        body = JSON.parse(text);
+    }
+    catch { /* not JSON */ }
+    if (!r.ok)
+        throw new Error(`upload failed (${r.status}): ${body?.error?.message ?? body?.error ?? body?.message ?? text.slice(0, 300)}`);
+    out(`Version ${body?.version ?? m.version}: ${body?.state ?? 'submitted'}`);
+    if (Array.isArray(body?.permission_diff) && body.permission_diff.length)
+        out(`New permissions: ${body.permission_diff.join(', ')}`);
+    if (Array.isArray(body?.findings))
+        printFindings(body.findings);
+    return body?.state !== 'rejected';
+}
+async function main() {
+    let argv = process.argv.slice(2);
+    if (argv[0] === 'knowledge')
+        return knowledge(parseArgs(argv.slice(1)).pos, out, err);
+    if (argv[0] === 'connector')
+        argv = argv.slice(1);
+    const { pos, flags } = parseArgs(argv);
+    const cmd = pos.shift();
+    const dir = resolve(typeof flags.dir === 'string' ? flags.dir : '.');
+    switch (cmd) {
+        case 'dev': return dev(dir, pos, flags);
+        case 'test': return test(dir);
+        case 'pack': {
+            const { file, sha256, tar, m } = packTo(dir, flags);
+            out(`${file}\n${m.id}@${m.version}  ${tar.length} bytes  sha256 ${sha256}`);
+            return true;
+        }
+        case 'sign': {
+            const target = pos[0] ? resolve(pos[0]) : packTo(dir, flags).file;
+            const tar = readFileSync(target);
+            const sha = sha256Hex(tar);
+            const { m } = load(dir);
+            const key = loadKey(typeof flags.key === 'string' ? flags.key : defaultKeyPath());
+            err(`${basename(target)}  ${m.id}@${m.version}  sha256 ${sha}`);
+            out(signBundle(key, m.id, m.version, sha));
+            return true;
+        }
+        case 'keygen': {
+            const path = typeof flags.key === 'string' ? flags.key : defaultKeyPath();
+            if (flags.show === true || (existsSync(path) && flags.force !== true)) {
+                out(publicKeyBase64(loadKey(path)));
+                err(`Existing key at ${path}. Pass --force to replace it.`);
+                return true;
+            }
+            const pub = keygen(path, flags.force === true);
+            err(`Saved your signing key to ${path}. Keep it private and backed up.`);
+            err('Register this public key in the console under Connectors, Signing keys:');
+            out(pub);
+            return true;
+        }
+        case 'publish': return publish(dir, flags);
+        case undefined:
+        case 'help':
+            out(HELP);
+            return true;
+        default:
+            err(`Unknown command ${cmd}.\n`);
+            out(HELP);
+            return false;
+    }
+}
+main().then((ok) => { stopHttpWorker(); process.exitCode = ok ? 0 : 1; }, (e) => { stopHttpWorker(); err(`Error  ${e.message}`); process.exitCode = 1; });

package/dist/host.d.ts

@@ -0,0 +1,81 @@
+import { type Canonical } from './manifest.js';
+import type { EgressOptions } from './net.js';
+import { type HostBridge } from './runner.js';
+export interface HostEvent {
+    op: string;
+    detail: string;
+}
+declare abstract class BaseHost implements HostBridge {
+    protected m: Canonical;
+    protected config: unknown;
+    protected granted: string[];
+    readonly events: HostEvent[];
+    constructor(m: Canonical, config: unknown, granted: string[]);
+    protected abstract storeGet(key: string): unknown;
+    protected abstract storeSet(key: string, value: unknown): void;
+    protected abstract storeDelete(key: string): void;
+    protected abstract fetch(args: any, deadline: number): unknown;
+    protected abstract upsert(records: unknown[]): unknown;
+    /** ctx.knowledge.*: printed locally, accepted in review. */
+    protected abstract knowledge(kind: 'upsert' | 'delete', items: unknown[]): unknown;
+    protected abstract log(level: string, message: string): void;
+    /** The install secret `name`, or undefined. */
+    protected abstract secret(name: string): string | undefined;
+    call(op: string, args: any, deadline: number): unknown;
+}
+/** crypto.rs fill_secrets: each `{{secrets.x}}` becomes that declared secret. */
+export declare function fillSecrets(text: string, secret: (name: string) => string | undefined): string;
+/** crypto.rs host_op: `{{secrets.x}}` in the message is filled in, keys never leave the host. */
+export declare function cryptoOp(op: string, args: any, secret: (name: string) => string | undefined): string;
+export declare class LocalHost extends BaseHost {
+    private secrets;
+    private storePath;
+    private egress;
+    private out;
+    private store;
+    constructor(m: Canonical, config: unknown, secrets: Record<string, string>, storePath: string, egress: EgressOptions, out: (line: string) => void);
+    private save;
+    protected storeGet(key: string): unknown;
+    protected storeSet(key: string, value: unknown): void;
+    protected storeDelete(key: string): void;
+    protected fetch(args: any, deadline: number): {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    };
+    protected upsert(records: unknown[]): {
+        local: boolean;
+        count: number;
+    };
+    protected knowledge(kind: 'upsert' | 'delete', items: unknown[]): {
+        local: boolean;
+        deleted: boolean;
+        results?: undefined;
+    } | {
+        local: boolean;
+        results: {
+            result: string;
+        }[];
+        deleted?: undefined;
+    };
+    protected secret(name: string): string | undefined;
+    protected log(level: string, message: string): void;
+}
+export declare class ReviewHost extends BaseHost {
+    private store;
+    constructor(m: Canonical, config: unknown);
+    protected storeGet(key: string): unknown;
+    protected storeSet(key: string, value: unknown): void;
+    protected storeDelete(key: string): void;
+    protected fetch(): never;
+    protected upsert(): {
+        review: boolean;
+    };
+    protected knowledge(): {
+        review: boolean;
+    };
+    protected log(): void;
+    protected secret(): string;
+    call(op: string, args: any, deadline: number): unknown;
+}
+export {};