@airfone/connector 0.0.0-stage → 0.1.0

package/dist/knowledge.js

@@ -0,0 +1,141 @@
+// airfone knowledge push|delete|sources: keep a workspace's knowledge in sync
+// with your own system through the /v1/knowledge push API. Records are
+// upserted by (source, external_id); pushing the same content again is a
+// no-op, so a nightly full push is cheap.
+import { readFileSync } from 'node:fs';
+export const KNOWLEDGE_HELP = `airfone knowledge <command>
+
+Commands
+  push <source> <file>       Upsert the records in a JSON array or JSON Lines file
+                             into <source> (a-z, 0-9, - and _). 500 per request.
+  delete <source> <id>       Delete one record by its external_id.
+  sources                    List your sources with record counts.
+
+Each record: {"external_id", "kind", "name", "aliases"?, "facts": [{"relation",
+"text", "audience"?, "volatile"?, "valid_from"?, "valid_to"?}], "links"?, "updated_at"?}
+
+Needs AIRFONE_KEY (a secret API key with knowledge:write) or AIRFONE_TOKEN, and
+AIRFONE_API (default https://app.airfone.app).`;
+const BATCH = 500;
+const RETRIES = 5;
+function auth() {
+    const token = process.env.AIRFONE_KEY ?? process.env.AIRFONE_TOKEN;
+    if (!token)
+        throw new Error('set AIRFONE_KEY (a secret API key) or AIRFONE_TOKEN');
+    const api = (process.env.AIRFONE_API ?? 'https://app.airfone.app').replace(/\/$/, '');
+    return { api, headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', 'Content-Type': 'application/json' } };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A request, retried on 429 and 5xx with backoff (Retry-After honoured). */
+async function call(method, url, headers, body) {
+    for (let attempt = 0;; attempt++) {
+        let r;
+        try {
+            r = await fetch(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+        }
+        catch (e) {
+            if (attempt >= RETRIES)
+                throw e;
+            await sleep(500 * 2 ** attempt);
+            continue;
+        }
+        if ((r.status === 429 || r.status >= 500) && attempt < RETRIES) {
+            const after = Number(r.headers.get('retry-after'));
+            await sleep(Number.isFinite(after) && after > 0 ? after * 1000 : 500 * 2 ** attempt);
+            continue;
+        }
+        const text = await r.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            json = text;
+        }
+        return { status: r.status, json };
+    }
+}
+function message(json) {
+    return json?.error?.message ?? json?.message ?? (typeof json === 'string' ? json.slice(0, 300) : JSON.stringify(json));
+}
+/** Records from a JSON array file or a JSON Lines file. */
+export function readRecords(path) {
+    const text = readFileSync(path, 'utf8').trim();
+    if (text.startsWith('[')) {
+        const all = JSON.parse(text);
+        if (!Array.isArray(all))
+            throw new Error(`${path}: expected an array of records`);
+        return all;
+    }
+    return text.split('\n').filter((l) => l.trim()).map((line, i) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch (e) {
+            throw new Error(`${path} line ${i + 1}: ${e.message}`);
+        }
+    });
+}
+async function push(source, file, out, err) {
+    const { api, headers } = auth();
+    const records = readRecords(file);
+    let written = 0, unchanged = 0, failed = 0;
+    for (let i = 0; i < records.length; i += BATCH) {
+        const batch = records.slice(i, i + BATCH);
+        const { status, json } = await call('POST', `${api}/v1/knowledge/sources/${encodeURIComponent(source)}/records`, headers, { records: batch });
+        if (status !== 200)
+            throw new Error(`batch ${i / BATCH + 1} refused (${status}): ${message(json)}`);
+        written += json.written ?? 0;
+        unchanged += json.unchanged ?? 0;
+        failed += json.failed ?? 0;
+        for (const r of json.results ?? []) {
+            if (r.result === 'error')
+                err(`  ${r.external_id || '(no external_id)'}: ${r.error}`);
+        }
+    }
+    out(`${records.length} records: ${written} written, ${unchanged} unchanged, ${failed} failed`);
+    return failed === 0;
+}
+async function remove(source, id, out) {
+    const { api, headers } = auth();
+    const { status, json } = await call('DELETE', `${api}/v1/knowledge/sources/${encodeURIComponent(source)}/records/${encodeURIComponent(id)}`, headers);
+    if (status === 204) {
+        out(`Deleted ${id} from ${source}`);
+        return true;
+    }
+    throw new Error(`delete failed (${status}): ${message(json)}`);
+}
+async function sources(out) {
+    const { api, headers } = auth();
+    const { status, json } = await call('GET', `${api}/v1/knowledge/sources`, headers);
+    if (status !== 200)
+        throw new Error(`could not list sources (${status}): ${message(json)}`);
+    if (!json.length)
+        out('No sources yet. Push records with: airfone knowledge push <source> <file>');
+    for (const s of json)
+        out(`${s.source}  ${s.records} records  ${s.deleted} deleted  last ${s.last_received_at ?? '-'}`);
+    return true;
+}
+export async function knowledge(pos, out, err) {
+    const cmd = pos.shift();
+    switch (cmd) {
+        case 'push':
+            if (pos.length < 2)
+                throw new Error('usage: airfone knowledge push <source> <file>');
+            return push(pos[0], pos[1], out, err);
+        case 'delete':
+            if (pos.length < 2)
+                throw new Error('usage: airfone knowledge delete <source> <external_id>');
+            return remove(pos[0], pos[1], out);
+        case 'sources':
+            return sources(out);
+        case undefined:
+        case 'help':
+            out(KNOWLEDGE_HELP);
+            return true;
+        default:
+            err(`Unknown command ${cmd}.\n`);
+            out(KNOWLEDGE_HELP);
+            return false;
+    }
+}

package/dist/manifest.d.ts

@@ -0,0 +1,39 @@
+import type { Action, Manifest } from './types.js';
+export declare const SCOPES: string[];
+export declare class ManifestError extends Error {
+}
+/** Canonical manifest: what the server stores after normalize(). */
+export interface Canonical extends Omit<Manifest, 'auth' | 'actions' | 'permissions' | 'config'> {
+    auth: {
+        kind: string;
+        [k: string]: unknown;
+    };
+    config: Record<string, unknown>;
+    permissions: {
+        hosts: string[];
+        scopes: string[];
+    };
+    actions: (Action & {
+        kind: 'http' | 'js';
+        confirm: 'none' | 'caller' | 'staff';
+    })[];
+}
+/** Accepts the published developer format and rewrites it to the canonical one. */
+export declare function normalize(raw: any): any;
+export declare function validId(id: string): boolean;
+export declare const configHostField: (e: string) => string | null;
+export declare function validHostPattern(host: string): boolean;
+/** Checks a value against a schema, like the server's check_schema(). */
+export declare function checkSchema(what: string, schema: unknown, value: unknown): void;
+/** Parses manifest.json text into the canonical manifest, or throws ManifestError. */
+export declare function parseManifest(text: string): Canonical;
+/** net.rs host_allowed(). */
+export declare function hostAllowed(patterns: string[], host: string): boolean;
+/** Every secret an install holds: the ones auth names, then `secrets` (manifest.rs secret_names). */
+export declare function secretNames(m: Canonical): string[];
+/** The config with each schema property's `default` filled in where missing (manifest.rs with_config_defaults). */
+export declare function withConfigDefaults(schema: unknown, config: unknown): Record<string, unknown>;
+/** Hosts this install may call: literal patterns plus the hosts of `{{config.x}}` URLs. */
+export declare function allowedHosts(m: Canonical, config: any): string[];
+/** Added hosts and scopes since a previous version (manifest.rs permission_diff). */
+export declare function permissionDiff(next: Canonical, prev: Canonical): string[];

package/dist/manifest.js

@@ -0,0 +1,316 @@
+// A port of backend/crates/connectors/src/manifest.rs: normalize() and
+// validate(). Same rules, same messages, so a manifest that passes here passes
+// the server's upload check.
+import Ajv2020Module from 'ajv/dist/2020.js';
+const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
+const ajv = new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
+export const SCOPES = ['records.read', 'records.write', 'contacts.read', 'messages.send', 'knowledge.write'];
+export class ManifestError extends Error {
+}
+/** Accepts the published developer format and rewrites it to the canonical one. */
+export function normalize(raw) {
+    const v = structuredClone(raw);
+    const auth = v?.auth;
+    if (auth && typeof auth === 'object') {
+        if (!('kind' in auth) && 'type' in auth) {
+            auth.kind = auth.type;
+            delete auth.type;
+        }
+        // format "Bearer {{secret}}": the text before the placeholder is the prefix.
+        if (typeof auth.format === 'string') {
+            const at = auth.format.indexOf('{{secret}}');
+            if (at >= 0 && !('prefix' in auth))
+                auth.prefix = auth.format.slice(0, at);
+            delete auth.format;
+        }
+        const kind = auth.kind ?? 'none';
+        const def = (k, val) => { if (!(k in auth))
+            auth[k] = val; };
+        if (kind === 'api_key') {
+            def('secret', 'api_key');
+            if (typeof auth.header === 'string') {
+                if (!('name' in auth))
+                    auth.name = auth.header;
+                if (!('in' in auth))
+                    auth.in = 'header';
+            }
+            else if (typeof auth.query === 'string') {
+                if (!('name' in auth))
+                    auth.name = auth.query;
+                if (!('in' in auth))
+                    auth.in = 'query';
+            }
+            delete auth.header;
+            delete auth.query;
+        }
+        else if (kind === 'basic') {
+            def('username', 'username');
+            def('password', 'password');
+        }
+        else if (kind === 'oauth')
+            def('secret', 'access_token');
+        else if (kind === 'bearer')
+            def('secret', 'token');
+        if (kind === 'oauth')
+            for (const k of Object.keys(auth))
+                if (!['kind', 'secret', 'scopes', 'prefix', 'token_url'].includes(k))
+                    delete auth[k];
+    }
+    const scopes = v?.permissions?.scopes;
+    if (Array.isArray(scopes))
+        v.permissions.scopes = scopes.map((s) => typeof s === 'string' ? s.replaceAll(':', '.') : s);
+    if (Array.isArray(v?.actions)) {
+        for (const a of v.actions) {
+            if (a && typeof a === 'object' && !('kind' in a))
+                a.kind = 'http' in a ? 'http' : 'js';
+            if (a?.http && typeof a.http === 'object' && 'map' in a.http && !('output' in a.http)) {
+                a.http.output = a.http.map;
+                delete a.http.map;
+            }
+        }
+    }
+    return v;
+}
+export function validId(id) {
+    return /^[a-z0-9._-]+$/.test(id) && id.length >= 2 && id.length <= 100 && /^[a-z0-9]/.test(id) && /[a-z0-9]$/.test(id) && !id.includes('..');
+}
+const validActionName = (n) => n.length > 0 && n.length <= 64 && n.split('.').every((p) => /^[a-z][A-Za-z0-9_]*$/.test(p));
+export const configHostField = (e) => e.startsWith('{{config.') && e.endsWith('}}') ? e.slice(9, -2) : null;
+export function validHostPattern(host) {
+    const bare = host.startsWith('*.') ? host.slice(2) : host;
+    return bare.length > 0 && bare.includes('.') && bare.length <= 253 && bare.split('.').every((l) => /^[a-z0-9-]+$/.test(l));
+}
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function compileSchema(what, schema) {
+    try {
+        ajv.compile(schema);
+    }
+    catch (e) {
+        throw new ManifestError(`${what} is not a valid JSON Schema: ${e.message}`);
+    }
+}
+/** Checks a value against a schema, like the server's check_schema(). */
+export function checkSchema(what, schema, value) {
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (e) {
+        throw new ManifestError(`${what} schema is invalid: ${e.message}`);
+    }
+    if (validate(value))
+        return;
+    const problems = (validate.errors ?? []).slice(0, 5).map((e) => (e.instancePath ? `${e.instancePath}: ` : '') + e.message);
+    throw new ManifestError(`${what} does not match its schema: ${problems.join('; ')}`);
+}
+const refs = (s) => [...s.matchAll(/\{\{(.*?)\}\}/g)].map((m) => m[1].trim());
+/** Parses manifest.json text into the canonical manifest, or throws ManifestError. */
+export function parseManifest(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new ManifestError(`manifest.json: ${e.message}`);
+    }
+    const m = normalize(raw);
+    const fail = (msg) => { throw new ManifestError(msg); };
+    if (!m || typeof m !== 'object')
+        fail('manifest.json: expected an object');
+    for (const k of ['id', 'version', 'name'])
+        if (typeof m[k] !== 'string')
+            fail(`manifest.json: missing field \`${k}\``);
+    if (!Array.isArray(m.actions))
+        fail('manifest.json: missing field `actions`');
+    m.description ??= '';
+    m.category ??= 'other';
+    m.sensitive ??= false;
+    m.regions ??= [];
+    m.auth ??= { kind: 'none' };
+    m.config ??= { type: 'object' };
+    m.permissions = { hosts: m.permissions?.hosts ?? [], scopes: m.permissions?.scopes ?? [] };
+    m.knowledge ??= [];
+    m.triggers ??= [];
+    m.ui ??= [];
+    m.secrets ??= [];
+    if (!['none', 'api_key', 'bearer', 'basic', 'oauth'].includes(m.auth.kind))
+        fail(`manifest.json: unknown auth kind ${JSON.stringify(m.auth.kind)}`);
+    if (m.auth.kind === 'api_key' && typeof m.auth.name !== 'string')
+        fail('manifest.json: api_key auth needs `header` or `query`');
+    if (!Array.isArray(m.secrets))
+        fail('manifest.json: `secrets` is a list');
+    for (const sec of m.secrets) {
+        if (typeof sec?.name !== 'string' || !/^[A-Za-z0-9_]+$/.test(sec.name))
+            fail(`secret name ${JSON.stringify(sec?.name)}: letters, digits and _`);
+        sec.title ??= '';
+        sec.description ??= '';
+    }
+    if (!validId(m.id))
+        fail(`id ${JSON.stringify(m.id)} must be lowercase reverse-DNS, like "np.daraz.seller"`);
+    if (!SEMVER.test(m.version))
+        fail(`version ${JSON.stringify(m.version)} is not semver`);
+    if (!m.name.trim() || [...m.name].length > 80)
+        fail('name must be 1 to 80 characters');
+    if ([...m.description].length > 2000)
+        fail('description is over 2000 characters');
+    for (const host of m.permissions.hosts) {
+        const field = configHostField(host);
+        if (field !== null) {
+            if (!field || !/^[A-Za-z0-9_]+$/.test(field))
+                fail(`host ${JSON.stringify(host)}: use {{config.<field>}}`);
+            continue;
+        }
+        if (!validHostPattern(host))
+            fail(`host ${JSON.stringify(host)} must be a bare lowercase host name like "api.example.com" or "*.example.com"`);
+    }
+    for (const s of m.permissions.scopes)
+        if (!SCOPES.includes(s))
+            fail(`unknown scope ${JSON.stringify(s)}; known: ${SCOPES.join(', ')}`);
+    if (m.sensitive && m.regions.length === 0 && m.permissions.hosts.length > 0)
+        fail('a sensitive connector must declare the regions of its hosts');
+    compileSchema('config', m.config);
+    if (m.actions.length === 0)
+        fail('a connector needs at least one action');
+    if (m.actions.length > 100)
+        fail('at most 100 actions');
+    const seen = new Set();
+    for (const a of m.actions) {
+        const n = a.name;
+        const q = JSON.stringify(n);
+        if (typeof n !== 'string' || !validActionName(n))
+            fail(`action name ${q} must be lowercase words joined by dots, like "order.create"`);
+        if (seen.has(n))
+            fail(`action ${q} is declared twice`);
+        seen.add(n);
+        if (typeof a.description !== 'string' || !a.description.trim())
+            fail(`action ${q} needs a description`);
+        if (!['read', 'change', 'money'].includes(a.risk))
+            fail(`action ${q}: risk is read, change or money`);
+        a.confirm ??= 'none';
+        if (!['none', 'caller', 'staff'].includes(a.confirm))
+            fail(`action ${q}: confirm is none, caller or staff`);
+        if (a.input === undefined)
+            fail(`action ${q}: missing field \`input\``);
+        if (a.output === undefined)
+            fail(`action ${q}: missing field \`output\``);
+        compileSchema(`action ${q} input`, a.input);
+        compileSchema(`action ${q} output`, a.output);
+        if (a.cache_seconds !== undefined && (!Number.isInteger(a.cache_seconds) || a.cache_seconds < 0))
+            fail(`action ${q}: cache_seconds is a whole number of seconds`);
+        if ((a.cache_seconds ?? 0) > 0 && a.risk !== 'read')
+            fail(`action ${q} changes something, so it cannot be cached`);
+        if ((a.cache_seconds ?? 0) > 300)
+            fail(`action ${q}: cache_seconds is at most 300`);
+        if (a.risk === 'money' && a.confirm === 'none')
+            fail(`action ${q} moves money, so it must need confirmation (caller or staff)`);
+        if (a.kind === 'http' && !a.http)
+            fail(`http action ${q} needs an \`http\` block`);
+        if (a.kind === 'js' && a.http)
+            fail(`js action ${q} must not have an \`http\` block`);
+        if (a.kind === 'http')
+            validateHttp(m, n, a.http);
+        a.fixtures ??= [];
+    }
+    for (const k of m.knowledge)
+        if (!m.actions.some((a) => a.name === k.action))
+            fail(`knowledge ${JSON.stringify(k.name)} names unknown action ${JSON.stringify(k.action)}`);
+    for (const t of m.triggers)
+        if (!['webhook', 'schedule'].includes(t.source))
+            fail(`trigger ${JSON.stringify(t.name)}: source is webhook or schedule`);
+    for (const p of m.ui) {
+        if (!['main', 'contact', 'inbox'].includes(p.placement) || !String(p.entry).startsWith('ui/') || String(p.entry).includes('..'))
+            fail(`ui panel ${JSON.stringify(p.name)}: placement main|contact|inbox and an entry under ui/`);
+        const bad = (p.bridge_apis ?? []).find((a) => !['auth.session', 'ui.toast', 'ui.resize', 'nav.open', 'contact.current'].includes(a));
+        if (bad)
+            fail(`ui panel ${JSON.stringify(p.name)}: unknown bridge call ${JSON.stringify(bad)}`);
+    }
+    return m;
+}
+function validateHttp(m, action, spec) {
+    const q = JSON.stringify(action);
+    const fail = (msg) => { throw new ManifestError(msg); };
+    if (typeof spec.method !== 'string' || typeof spec.url !== 'string')
+        fail(`action ${q}: http needs method and url`);
+    if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(spec.method.toUpperCase()))
+        fail(`action ${q}: method ${spec.method} not allowed`);
+    const refsSecret = (s) => refs(s).some((r) => r.startsWith('secrets.'));
+    if (refsSecret(spec.url))
+        fail(`action ${q}: secrets may go in headers or query only, not the URL`);
+    if (spec.body !== undefined && refsSecret(JSON.stringify(spec.body)))
+        fail(`action ${q}: secrets may go in headers or query only, not the body`);
+    if (spec.fail_when !== undefined && !Array.isArray(spec.fail_when))
+        fail(`action ${q}: fail_when is a list`);
+    for (const rule of spec.fail_when ?? []) {
+        for (const path of [rule?.path, ...(rule?.message_path === undefined ? [] : [rule.message_path])]) {
+            if (typeof path !== 'string' || !path.startsWith('$'))
+                fail(`action ${q}: fail_when path ${JSON.stringify(path)}: a JSONPath starting with $`);
+        }
+    }
+    if (spec.url.startsWith('{{config.'))
+        return;
+    if (!spec.url.startsWith('https://'))
+        fail(`action ${q}: the URL must start with https:// or {{config.<field>}}`);
+    const host = spec.url.slice(8).split(/[/?:]/)[0];
+    if (!host || host.includes('{{'))
+        fail(`action ${q}: the URL host must be literal`);
+    const literal = m.permissions.hosts.filter((h) => !h.startsWith('{{'));
+    if (!hostAllowed(literal, host))
+        fail(`action ${q} calls ${host}, which is not in permissions.hosts`);
+}
+/** net.rs host_allowed(). */
+export function hostAllowed(patterns, host) {
+    return patterns.some((p) => p.startsWith('*.') ? host.length > p.length - 1 && host.endsWith(p.slice(1)) : host === p);
+}
+/** Every secret an install holds: the ones auth names, then `secrets` (manifest.rs secret_names). */
+export function secretNames(m) {
+    const a = m.auth;
+    const names = [];
+    if (a.kind === 'basic')
+        names.push(String(a.username), String(a.password));
+    else if (typeof a.secret === 'string' && a.kind !== 'none')
+        names.push(a.secret);
+    for (const s of m.secrets ?? [])
+        if (!names.includes(s.name))
+            names.push(s.name);
+    return names;
+}
+/** The config with each schema property's `default` filled in where missing (manifest.rs with_config_defaults). */
+export function withConfigDefaults(schema, config) {
+    const out = config && typeof config === 'object' && !Array.isArray(config) ? { ...config } : {};
+    const props = schema?.properties;
+    if (props && typeof props === 'object')
+        for (const [k, p] of Object.entries(props))
+            if (p && typeof p === 'object' && 'default' in p && !(k in out))
+                out[k] = p.default;
+    return out;
+}
+/** Hosts this install may call: literal patterns plus the hosts of `{{config.x}}` URLs. */
+export function allowedHosts(m, config) {
+    const out = [];
+    for (const entry of m.permissions.hosts) {
+        const field = configHostField(entry);
+        if (field === null) {
+            out.push(entry);
+            continue;
+        }
+        try {
+            const u = new URL(String(config?.[field]));
+            out.push(u.hostname.toLowerCase());
+        }
+        catch { /* not set */ }
+    }
+    return out;
+}
+/** Added hosts and scopes since a previous version (manifest.rs permission_diff). */
+export function permissionDiff(next, prev) {
+    const added = [];
+    for (const h of next.permissions.hosts)
+        if (!prev.permissions.hosts.includes(h))
+            added.push(`host ${h}`);
+    for (const s of next.permissions.scopes)
+        if (!prev.permissions.scopes.includes(s))
+            added.push(`scope ${s}`);
+    if (next.sensitive && !prev.sensitive)
+        added.push('sensitive');
+    return added;
+}

package/dist/net.d.ts

@@ -0,0 +1,20 @@
+export declare const MAX_RESPONSE_BYTES: number;
+export declare const HTTP_TIMEOUT_MS = 10000;
+export interface OutRequest {
+    method: string;
+    url: string;
+    headers: [string, string][];
+    query: [string, string][];
+    body: string | null;
+}
+export interface OutResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface EgressOptions {
+    /** `--allow-local`: lets http:// and private addresses through, for a mock server on your machine. Never true on AirFone. */
+    allowLocal?: boolean;
+}
+export declare function isBlockedIp(ip: string): boolean;
+export declare function send(allowed: string[], req: OutRequest, opts?: EgressOptions): Promise<OutResponse>;

package/dist/net.js

@@ -0,0 +1,73 @@
+// Outbound HTTP for local runs, with the server's rules (net.rs): only
+// declared hosts, https only, never private or local addresses after DNS,
+// no redirects, at most 4 MB of response, 10 s per request.
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { hostAllowed } from './manifest.js';
+export const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+export const HTTP_TIMEOUT_MS = 10_000;
+function blockedV4(ip) {
+    const o = ip.split('.').map(Number);
+    return o[0] === 127 || o[0] === 10 || (o[0] === 172 && o[1] >= 16 && o[1] <= 31) || (o[0] === 192 && o[1] === 168)
+        || (o[0] === 169 && o[1] === 254) || o[0] === 0 || o[0] >= 224
+        || (o[0] === 100 && (o[1] & 0xc0) === 64) || (o[0] === 192 && o[1] === 0 && o[2] === 0) || (o[0] === 198 && (o[1] & 0xfe) === 18)
+        || (o[0] === 192 && o[1] === 0 && o[2] === 2) || (o[0] === 198 && o[1] === 51 && o[2] === 100) || (o[0] === 203 && o[1] === 0 && o[2] === 113);
+}
+export function isBlockedIp(ip) {
+    if (isIP(ip) === 4)
+        return blockedV4(ip);
+    const v6 = ip.toLowerCase();
+    const mapped = v6.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped)
+        return blockedV4(mapped[1]);
+    return v6 === '::1' || v6 === '::' || v6.startsWith('fe8') || v6.startsWith('fe9') || v6.startsWith('fea') || v6.startsWith('feb')
+        || v6.startsWith('fc') || v6.startsWith('fd') || v6.startsWith('ff') || v6.startsWith('64:ff9b:') || v6.startsWith('2001:db8');
+}
+export async function send(allowed, req, opts = {}) {
+    let url;
+    try {
+        url = new URL(req.url);
+    }
+    catch {
+        throw new Error(`bad URL ${req.url}`);
+    }
+    if (url.protocol !== 'https:' && !(opts.allowLocal && url.protocol === 'http:'))
+        throw new Error('only https URLs are allowed');
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    const testIp = opts.allowLocal && isIP(host) !== 0;
+    if (!testIp && !hostAllowed(allowed, host))
+        throw new Error(`host ${host} is not declared in permissions.hosts`);
+    const addrs = isIP(host) ? [{ address: host }] : await lookup(host, { all: true }).catch((e) => { throw new Error(`cannot resolve ${host}: ${e.code ?? e.message}`); });
+    if (!addrs.length)
+        throw new Error(`${host} has no address`);
+    if (!opts.allowLocal) {
+        const bad = addrs.find((a) => isBlockedIp(a.address));
+        if (bad)
+            throw new Error(`${host} resolves to a private address (${bad.address})`);
+    }
+    for (const [k, v] of req.query)
+        url.searchParams.append(k, v);
+    const headers = new Headers();
+    for (const [k, v] of req.headers)
+        if (k.toLowerCase() !== 'host')
+            headers.append(k, v);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), HTTP_TIMEOUT_MS);
+    try {
+        const r = await fetch(url, { method: req.method, headers, body: req.body ?? undefined, redirect: 'manual', signal: ctrl.signal });
+        const buf = new Uint8Array(await r.arrayBuffer());
+        if (buf.length > MAX_RESPONSE_BYTES)
+            throw new Error(`${host} answered with more than ${MAX_RESPONSE_BYTES} bytes`);
+        const out = {};
+        r.headers.forEach((v, k) => { out[k] = v; });
+        return { status: r.status, headers: out, body: new TextDecoder().decode(buf) };
+    }
+    catch (e) {
+        if (e.name === 'AbortError')
+            throw new Error(`${host} timed out`);
+        throw new Error(`${host}: ${e.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/review.d.ts

@@ -0,0 +1,16 @@
+import { type Canonical } from './manifest.js';
+export interface Finding {
+    level: 'error' | 'warning';
+    message: string;
+}
+export interface Fixture {
+    action: string;
+    label: string;
+    input: unknown;
+    config?: unknown;
+    expect?: unknown;
+}
+export declare function subset(expected: unknown, actual: unknown): boolean;
+/** Fixtures from the manifest, plus tests/*.json files ({ action, input, config?, expect? } or an array of them). These run locally only. */
+export declare function fixtures(m: Canonical, dir: string): Fixture[];
+export declare function review(m: Canonical, js: string | null, list: Fixture[]): Promise<Finding[]>;