aurival 0.1.0

package/dist/auth.js

@@ -0,0 +1,416 @@
+/**
+ * The key file, first-run pairing, assertion signing, access-token exchange.
+ *
+ * SDK-33: the seed lives in exactly one object (`MachineKey`) and never leaves
+ * it — not a property anywhere else, not a local in dispatch, not in a log line
+ * or thrown message. Node's `KeyObject` keeps the bytes out of reach; the only
+ * path the b64 seed travels is `KeyFile.load` -> `MachineKey.fromSeedB64`
+ * (decoded immediately) and `MachineKey.seedB64ForSave` -> `KeyFile.save`
+ * (encoded only at the moment of writing).
+ */
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign as cryptoSign, } from 'node:crypto';
+import { inspect } from 'node:util';
+import { existsSync } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as errors from './errors.js';
+// Re-exported, not redefined: bot.ts compares the resolved host against http's
+// copy, and two spellings of one default drift silently.
+export { DEFAULT_HOST } from './http.js';
+import { DEFAULT_HOST, defaultLogger } from './http.js';
+// token.go: AssertionMaxAge. auth owns 60s of refresh headroom ahead of a
+// 15-minute access-token TTL (SDK-37).
+const ASSERTION_MAX_AGE_S = 120;
+const TOKEN_REFRESH_HEADROOM_MS = 60_000;
+const DEFAULT_PAIR_RETRY_AFTER_MS = 60_000;
+// botapi.go:158 — a custom base32 alphabet, no padding. Not RFC 4648.
+const B32_ALPHABET = '0123456789abcdefghjkmnpqrstvwxyz';
+function b32encodeNopad(data) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of data) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            const index = (value >>> (bits - 5)) & 0x1f;
+            out += B32_ALPHABET.charAt(index);
+            bits -= 5;
+        }
+    }
+    if (bits > 0) {
+        out += B32_ALPHABET.charAt((value << (5 - bits)) & 0x1f);
+    }
+    return out;
+}
+function fingerprintOf(canonicalB64) {
+    // botapi.go:206 — hashes the canonical base64 STRING, not the raw bytes.
+    const digest = createHash('sha256').update(Buffer.from(canonicalB64, 'ascii')).digest();
+    const s = b32encodeNopad(digest).slice(0, 8);
+    return (s.slice(0, 4) + '-' + s.slice(4)).toUpperCase();
+}
+function b64urlNopad(data) {
+    return Buffer.from(data).toString('base64url');
+}
+function parseRfc3339(s) {
+    // time.RFC3339 in Go always has a "Z" or numeric offset; `Date.parse`
+    // handles both natively, unlike Python's fromisoformat quirk with "Z".
+    const ms = Date.parse(s);
+    if (Number.isNaN(ms)) {
+        throw new errors.ProtocolError(`expires_at was not a valid RFC3339 timestamp: ${s}`);
+    }
+    return ms;
+}
+// RFC 8410 PKCS8 wrapper for a raw 32-byte Ed25519 private key (the seed).
+// Node has no "import raw Ed25519 private bytes" API; this DER prefix plus
+// the seed is the whole PKCS8 document, and Node/OpenSSL derives the public
+// key from it lazily — no `x` (public) component needs to be supplied.
+const ED25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+function privateKeyFromSeed(seed) {
+    return createPrivateKey({
+        key: Buffer.concat([ED25519_PKCS8_PREFIX, seed]),
+        format: 'der',
+        type: 'pkcs8',
+    });
+}
+const SEED_LENGTH = 32;
+/** The ONLY object that holds the seed (SDK-33). */
+export class MachineKey {
+    #privateKey;
+    constructor(privateKey) {
+        this.#privateKey = privateKey;
+    }
+    static generate() {
+        const { privateKey } = generateKeyPairSync('ed25519');
+        return new MachineKey(privateKey);
+    }
+    static fromSeedB64(seedB64) {
+        const seed = Buffer.from(seedB64, 'base64');
+        if (seed.length !== SEED_LENGTH) {
+            throw new errors.ProtocolError(`ed25519 seed must be ${SEED_LENGTH} bytes, got ${seed.length}`);
+        }
+        return new MachineKey(privateKeyFromSeed(seed));
+    }
+    sign(payload) {
+        return cryptoSign(null, Buffer.from(payload), this.#privateKey);
+    }
+    get publicKeyB64() {
+        const jwk = createPublicKey(this.#privateKey).export({ format: 'jwk' });
+        return Buffer.from(jwk.x, 'base64url').toString('base64');
+    }
+    get fingerprint() {
+        return fingerprintOf(this.publicKeyB64);
+    }
+    /** The seed's one legitimate exit. Called ONLY by `KeyFile.save`. */
+    seedB64ForSave() {
+        const jwk = this.#privateKey.export({ format: 'jwk' });
+        return Buffer.from(jwk.d, 'base64url').toString('base64');
+    }
+    toString() {
+        return `<MachineKey fingerprint=${this.fingerprint}>`;
+    }
+    [inspect.custom]() {
+        return this.toString();
+    }
+}
+export class KeyFile {
+    path;
+    isDefault;
+    constructor(filePath) {
+        if (filePath != null) {
+            this.path = filePath;
+            this.isDefault = false;
+        }
+        else {
+            const override = process.env['AURIVAL_KEY_PATH'];
+            if (override) {
+                this.path = override;
+                this.isDefault = false;
+            }
+            else {
+                this.path = KeyFile.defaultPath();
+                this.isDefault = true;
+            }
+        }
+    }
+    static defaultPath() {
+        return path.join('.aurival', 'machine.json');
+    }
+    async load() {
+        let raw;
+        try {
+            raw = await fs.readFile(this.path, 'utf8');
+        }
+        catch (exc) {
+            if (isNoEnt(exc))
+                return null;
+            throw exc;
+        }
+        const doc = JSON.parse(raw);
+        const key = MachineKey.fromSeedB64(doc.seed);
+        const machine = {
+            bot: doc.bot,
+            machine: doc.machine,
+            host: doc.host,
+            created: doc.created,
+        };
+        return { key, machine };
+    }
+    async save(key, machine) {
+        const directory = path.dirname(this.path);
+        await fs.mkdir(directory, { recursive: true });
+        await fs.chmod(directory, 0o700);
+        const doc = {
+            seed: key.seedB64ForSave(),
+            bot: machine.bot,
+            machine: machine.machine,
+            host: machine.host,
+            created: machine.created,
+        };
+        const tmpName = path.join(directory, `.machine-${randomBytes(8).toString('hex')}.tmp`);
+        try {
+            await fs.writeFile(tmpName, JSON.stringify(doc), { encoding: 'utf8', mode: 0o600 });
+            await fs.chmod(tmpName, 0o600);
+            await fs.rename(tmpName, this.path);
+        }
+        catch (exc) {
+            await fs.unlink(tmpName).catch(() => undefined);
+            throw exc;
+        }
+        if (this.isDefault) {
+            await fs.writeFile(path.join(directory, '.gitignore'), '*\n', 'utf8');
+        }
+    }
+}
+function isNoEnt(exc) {
+    return typeof exc === 'object' && exc !== null && exc.code === 'ENOENT';
+}
+export class Auth {
+    bot;
+    #http;
+    #key;
+    #machineId;
+    #logger;
+    /** Only ever read to name the file in a `key_revoked` message (S7). */
+    #keyPath;
+    #token = null;
+    #expiresAtMs = null;
+    /** Serializes concurrent callers against `#token`/`#expiresAtMs` mutation;
+     * unlike a cached in-flight promise, each queued caller still performs its
+     * own exchange when it is `refresh()` doing the calling (SDK-37). */
+    #chain = Promise.resolve();
+    constructor(http, key, machine, logger, keyPath) {
+        this.#http = http;
+        this.#key = key;
+        this.#machineId = machine.machine;
+        this.bot = machine.bot;
+        this.#logger = logger ?? defaultLogger();
+        this.#keyPath = keyPath ?? null;
+    }
+    #fresh() {
+        return (this.#token !== null &&
+            this.#expiresAtMs !== null &&
+            Date.now() < this.#expiresAtMs - TOKEN_REFRESH_HEADROOM_MS);
+    }
+    async token() {
+        if (this.#fresh()) {
+            return this.#token;
+        }
+        return this.refresh();
+    }
+    async refresh() {
+        // Unconditional: `token()` checks freshness before calling this,
+        // `refresh()` itself always performs a new exchange. Chaining onto
+        // `#chain` only serializes attempts against the shared fields below.
+        const run = this.#chain.then(() => this.#exchange());
+        this.#chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async #exchange() {
+        const assertion = this.buildAssertion();
+        let resp;
+        try {
+            resp = await this.#http.request('POST', '/v1/token', {
+                body: { assertion },
+                authenticated: false,
+            });
+        }
+        catch (exc) {
+            throw this.#nameTheKeyFile(exc);
+        }
+        const token = resp['access_token'];
+        if (typeof token !== 'string') {
+            throw new errors.ProtocolError('token response missing access_token');
+        }
+        const expiresAt = resp['expires_at'];
+        this.#expiresAtMs = parseRfc3339(String(expiresAt));
+        this.#token = token;
+        this.#logger.debug('access token refreshed');
+        return token;
+    }
+    /**
+     * A revoked key cannot be retried out of, and the fix is deleting a file the
+     * developer has probably never opened. The SAME error object comes back with
+     * its message extended — the README documents catching `KeyRevoked`, so
+     * wrapping it in something new would break the contract it is here to serve.
+     */
+    #nameTheKeyFile(exc) {
+        if (!(exc instanceof errors.KeyRevoked))
+            return exc;
+        const keyPath = this.#keyPath ?? KeyFile.defaultPath();
+        if (!existsSync(keyPath))
+            return exc;
+        // The server already says "generate a new keypair and pair again"; the one
+        // thing it cannot know is where this machine keeps its key.
+        exc.message = `${exc.message} Remove ${keyPath} and run the bot again to pair a new key.`;
+        return exc;
+    }
+    buildAssertion(now) {
+        const iat = Math.floor(now ?? Date.now() / 1000);
+        const exp = iat + ASSERTION_MAX_AGE_S;
+        const nonce = b64urlNopad(randomBytes(16));
+        const payload = {
+            key_id: this.#machineId,
+            bot_id: this.bot,
+            iat,
+            exp,
+            nonce,
+        };
+        const raw = Buffer.from(JSON.stringify(payload), 'utf8');
+        const sig = this.#key.sign(raw);
+        return `${b64urlNopad(raw)}.${b64urlNopad(sig)}`;
+    }
+}
+// pairing.go:64 falls back on the server side past 64 chars anyway; we
+// truncate up front so the sent label and the signed label always match.
+export function machineLabel() {
+    return os.hostname().slice(0, 64);
+}
+function isLoopbackHostname(hostname) {
+    if (hostname === 'localhost')
+        return true;
+    if (hostname === '::1' || hostname === '0:0:0:0:0:0:0:1')
+        return true;
+    const parts = hostname.split('.');
+    if (parts.length === 4 && parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255)) {
+        return parts[0] === '127';
+    }
+    return false;
+}
+export function resolveHost() {
+    const host = process.env['AURIVAL_API'];
+    if (!host)
+        return DEFAULT_HOST;
+    const fail = () => {
+        throw new Error(`AURIVAL_API must be https:// unless the host is loopback, got ${JSON.stringify(host)}`);
+    };
+    let parsed;
+    try {
+        parsed = new URL(host);
+    }
+    catch {
+        return fail();
+    }
+    // `new URL().hostname` brackets a literal IPv6 host, e.g. "[::1]".
+    let hostname = parsed.hostname;
+    if (hostname.startsWith('[') && hostname.endsWith(']')) {
+        hostname = hostname.slice(1, -1);
+    }
+    if (parsed.protocol !== 'https:' && !isLoopbackHostname(hostname)) {
+        return fail();
+    }
+    return host;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+async function pollUntilSettled(http, pollToken, intervalMs, host, signal) {
+    const headers = { Authorization: `Bearer ${pollToken}` };
+    for (;;) {
+        await sleep(intervalMs, signal);
+        let resp;
+        try {
+            resp = await http.request('POST', '/v1/pair/poll', { authenticated: false, headers });
+        }
+        catch (exc) {
+            if (exc instanceof errors.PairRateLimited) {
+                const wait = exc.retry_after !== null ? exc.retry_after * 1000 : DEFAULT_PAIR_RETRY_AFTER_MS;
+                await sleep(wait, signal);
+                continue;
+            }
+            throw exc;
+        }
+        const state = resp['state'];
+        if (state === 'pending')
+            continue;
+        if (state === 'expired')
+            return { machine: null, expired: true };
+        if (state === 'approved') {
+            const machine = {
+                bot: String(resp['bot']),
+                machine: String(resp['machine']),
+                host,
+                created: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+            };
+            return { machine, expired: false };
+        }
+        throw new errors.ProtocolError(`unknown pairing state: ${JSON.stringify(state)}`);
+    }
+}
+export async function pair(http, options) {
+    const log = options.logger ?? defaultLogger();
+    const label = options.machineLabel ?? machineLabel();
+    const out = options.out ?? ((line) => console.log(line));
+    const signal = options.signal;
+    const key = MachineKey.generate();
+    for (;;) {
+        const iat = Math.floor(Date.now() / 1000);
+        const proof = key.sign(Buffer.from(`pair-start:${label}:${iat}`, 'utf8'));
+        let start;
+        try {
+            start = await http.request('POST', '/v1/pair/start', {
+                authenticated: false,
+                body: {
+                    machine_label: label,
+                    public_key: key.publicKeyB64,
+                    proof: Buffer.from(proof).toString('base64'),
+                    iat,
+                },
+            });
+        }
+        catch (exc) {
+            if (exc instanceof errors.PairRateLimited) {
+                const wait = exc.retry_after !== null ? exc.retry_after * 1000 : DEFAULT_PAIR_RETRY_AFTER_MS;
+                log.info(`pairing rate limited, waiting ${(wait / 1000).toFixed(0)}s`);
+                await sleep(wait, signal);
+                continue;
+            }
+            throw exc;
+        }
+        const userCode = String(start['user_code']);
+        const fingerprint = String(start['fingerprint']);
+        const pollToken = String(start['poll_token']);
+        const intervalMs = Number(start['interval_ms']);
+        // Directly to stdout, never the logger (SDK-31) — a dev with the
+        // logger at WARNING must still see this. The lead's e2e matches these
+        // two lines verbatim: /pairing code\s+([0-9A-Z]{4}-[0-9A-Z]{4})/.
+        out(`aurival: pairing code    ${userCode}`);
+        out(`aurival: fingerprint     ${fingerprint}`);
+        out('Compare the fingerprint in the app, then approve. Waiting...');
+        const settled = await pollUntilSettled(http, pollToken, intervalMs, options.host, signal);
+        if (settled.machine !== null) {
+            return { key, machine: settled.machine };
+        }
+        log.info('pairing code expired, starting a new one');
+        out('That code expired. Here is a new one:');
+        // SDK-36: unbounded restart, one new code per restart. Loop again.
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/bot.d.ts

@@ -0,0 +1,76 @@
+/** The developer-facing surface: declare commands, call run(), we hold the socket. */
+import { KeyFile } from './auth.js';
+import type { Machine, MachineKey } from './auth.js';
+import { Context, Event } from './events.js';
+import { HttpClient } from './http.js';
+import type { Logger } from './http.js';
+export type Handler = (ctx: Context) => Promise<void> | void;
+/**
+ * The hook also receives a `backlog.overflowed` Event, which is operational
+ * rather than an error — it never reaches a handler (SDK-28).
+ */
+export type Reportable = unknown | Event;
+export type ErrorHook = (error: Reportable, ctx: Context | null) => Promise<void> | void;
+/** How long a clean shutdown waits for handlers that are still running (SDK-32). */
+export declare const SHUTDOWN_GRACE_MS = 10000;
+export interface BotOptions {
+    host?: string | undefined;
+    keyPath?: string | undefined;
+    logger?: Logger | undefined;
+}
+/**
+ * Load the key file, or pair this machine and save one.
+ *
+ * `Bot.start` and `aurival init` both come through here, so the code and the
+ * fingerprint print identically either way (SDK-43) — the printout is the thing
+ * a developer compares in the app, and two spellings of it would drift.
+ */
+export declare function ensurePaired(http: HttpClient, keyFile: KeyFile, host: string, log: Logger, signal: AbortSignal): Promise<{
+    key: MachineKey;
+    machine: Machine;
+    paired: boolean;
+}>;
+/**
+ * The one door to command sync, so the lane that syncs is always the lane that
+ * reports. Both `Bot` call sites go through here.
+ *
+ * Exported for the tests, not from `index.ts` — the package's export list
+ * mirrors Python's `__all__` (SDK-7) and this is not on it.
+ */
+export declare function syncCommandsAndReport(http: HttpClient, bot: string, payload: Array<{
+    name: string;
+    description: string;
+}>, log: Logger): Promise<void>;
+/**
+ * One warning line per shadowed chat (S11). Silently dropping `conflicts` is
+ * the silence the field exists to end: the developer whose command never fires.
+ *
+ * The wire carries chat references and deliberately not the other bot
+ * (server.go's handleReplaceCommands), so the chat id is all a line can name.
+ */
+export declare function reportConflicts(response: Record<string, unknown>, log: Logger): void;
+/**
+ * A bot. Register commands, then `run()`.
+ *
+ * First run pairs this machine: it prints a code, you approve it in the app, and
+ * the key lands in ./.aurival/. Every later run just starts.
+ */
+export declare class Bot {
+    #private;
+    constructor(options?: BotOptions);
+    /**
+     * Declare a command. The name is sent as written — the server is the
+     * validator (SDK-29), and it lowercases and trims before it checks.
+     */
+    command(name: string, handler: Handler): void;
+    command(name: string, description: string, handler: Handler): void;
+    /**
+     * Called with (error, context | null) for anything the SDK caught for you: a
+     * handler that threw, a `problem` frame, a backlog overflow.
+     */
+    onError(fn: ErrorHook): void;
+    /** Installs signal handlers and runs until SIGINT/SIGTERM or something fatal. */
+    run(): Promise<void>;
+    start(signal?: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=bot.d.ts.map

package/dist/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAQ,OAAO,EAAmC,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAgB,UAAU,EAAiB,MAAM,WAAW,CAAC;AAEpE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGxC,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,KAAK,CAAC;AACzC,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzF,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAaD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CAYjE;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,EACrD,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAcpF;AAED;;;;;GAKG;AACH,qBAAa,GAAG;;IASd,YAAY,OAAO,GAAE,UAAe,EAInC;IAID;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAQnE;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAE3B;IAID,iFAAiF;IAC3E,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAWzB;IAEK,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC/C;CA0HF"}