@threahq/bot-runtime-client 0.1.0

package/invocation-control.d.ts

@@ -0,0 +1,128 @@
+import type { AttachmentRef } from "./crypto.js";
+import { type BotIdentityKey, type SealingState } from "./sealed.js";
+export declare const BOT_INVOCATION_CANCELLATION_REASONS: readonly ["source_deleted", "routing_changed", "input_restart", "input_stale", "key_grant_lost"];
+export type InputUpdateDisposition = "applied" | "restart-required";
+export type BotInvocationCancellationReason = (typeof BOT_INVOCATION_CANCELLATION_REASONS)[number];
+export interface InvocationInputUpdate {
+    sourceRevision: number;
+    delivery: "plaintext" | "sealed";
+    promptMarkdown: string;
+    attachmentRefs: AttachmentRef[];
+    sealing?: SealingState;
+}
+export interface InvocationCancellation {
+    invocationId: string;
+    sourceRevision: number;
+    reason: BotInvocationCancellationReason;
+}
+export interface InvocationControlCallbacks {
+    onInputUpdated(update: InvocationInputUpdate, signal: AbortSignal): Promise<InputUpdateDisposition> | InputUpdateDisposition;
+    onCancelled(): Promise<void> | void;
+    /** The authoritative claim no longer exists, without a typed backend cancellation. */
+    onClaimLost?(): Promise<void> | void;
+}
+export interface ObserveClaimParams {
+    invocationId: string;
+    claimToken: string;
+    sourceRevision: number;
+    claimTtlSeconds: number;
+    instanceId?: string;
+    callbacks: InvocationControlCallbacks;
+    sealed?: {
+        identities: BotIdentityKey[];
+        streamId: string;
+        callbackToken: string;
+    };
+}
+export interface ObservedClaimHandle {
+    sync(): Promise<void>;
+    unregister(): void;
+    dispose(): void;
+}
+export type InvocationControlState = {
+    invocationId: string;
+    status: "active";
+    claimExpiresAt: string;
+    sourceRevision: number;
+    update?: unknown;
+} | {
+    invocationId: string;
+    status: "cancelled";
+    claimExpiresAt: null;
+    sourceRevision: number;
+    reason: BotInvocationCancellationReason;
+};
+export type ControlSyncResult = {
+    kind: "control";
+    state: InvocationControlState;
+} | {
+    kind: "not_found";
+} | {
+    kind: "retry";
+} | {
+    kind: "aborted";
+};
+export interface InvocationControlSyncRequest {
+    invocationId: string;
+    instanceId?: string;
+    claimToken: string;
+    claimTtlSeconds: number;
+    knownSourceRevision: number;
+    minimumSourceRevision: number;
+    restartRequiredRevision?: number;
+    ackTimeoutMs: number;
+    signal: AbortSignal;
+}
+export interface InvocationControlScheduler {
+    setTimeout(callback: () => void, delayMs: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+interface InvocationControlManagerOptions {
+    retryDelayMs?: number;
+    minRenewDelayMs?: number;
+    now?: () => number;
+    scheduler?: InvocationControlScheduler;
+}
+export declare class InvocationControlManager {
+    private readonly hooks;
+    private readonly observations;
+    private readonly pendingTerminalGenerations;
+    private queue;
+    private stopped;
+    private generation;
+    private readonly retryDelayMs;
+    private readonly minRenewDelayMs;
+    private readonly now;
+    private readonly scheduler;
+    constructor(hooks: {
+        sync(request: InvocationControlSyncRequest): Promise<ControlSyncResult>;
+        socketReady(): boolean;
+        log(message: string): void;
+    }, options?: InvocationControlManagerOptions);
+    observe(params: ObserveClaimParams): ObservedClaimHandle;
+    hint(payload: unknown, cancelled: boolean): void;
+    bootstrap(recentCancellations: unknown[], callback: () => void): Promise<void>;
+    wake(): void;
+    enqueueAdapter(callback: () => void): Promise<void>;
+    stop(): void;
+    private syncAndDrain;
+    private requestSync;
+    private runDrain;
+    private runSync;
+    private prepareUpdate;
+    private markRestartPending;
+    private highestLocallyKnownRevision;
+    private terminalizeCancellation;
+    private makeTerminal;
+    private unregister;
+    private teardown;
+    private scrub;
+    private schedule;
+    private isCurrent;
+    private enqueue;
+    private awaitStableControls;
+}
+export declare function parseCancellationReason(value: unknown): BotInvocationCancellationReason | undefined;
+export declare function parseInvocationCancellation(value: unknown): InvocationCancellation | undefined;
+export declare function parseRevision(value: unknown): number | undefined;
+export {};

package/keyring.d.ts

@@ -0,0 +1,242 @@
+/**
+ * The E2E keyring a bot runtime holds: the X25519 identity keys an owner wraps
+ * a sealed stream's key to, and where they live on the operator's machine.
+ *
+ * A runtime used to hold exactly one key per install. It now advertises a
+ * keyring, so several runtimes on one box can share a single key (the default —
+ * one key per host) and a key can be pinned to one stream. The server stores
+ * the advertised set as the instance's complete keyring and wraps every sealed
+ * stream key to each eligible member.
+ *
+ * Keys are secrets, so where they are kept is the operator's explicit choice:
+ * the OS keychain (driven through its command-line tool, which survives a
+ * runtime being rebuilt and reinstalled) or a `0600` file. There is no silent
+ * fallback between the two — an unavailable keychain is an error naming both
+ * options, not a quiet downgrade to disk.
+ */
+export declare const E2E_KEY_SCOPES: readonly ["host", "identity", "instance", "stream"];
+export type E2eKeyScope = (typeof E2E_KEY_SCOPES)[number];
+export declare const E2E_KEY_STORE_KINDS: readonly ["keychain", "file"];
+export type E2eKeyStoreKind = (typeof E2E_KEY_STORE_KINDS)[number];
+/** A key as it is persisted and as it rides presence: public half plus the private key, base64. */
+export interface E2eKeyRecord {
+    keyId: string;
+    publicKey: string;
+    privateKey: string;
+}
+/** A held key, the account it came from, and the stream it is pinned to, if any. */
+export interface HeldE2eKey extends E2eKeyRecord {
+    account: string;
+    streamId?: string;
+}
+/**
+ * A place a key record is kept. `createExclusive` never overwrites: when
+ * another process wrote the account first its record is returned instead, so
+ * two runtimes racing to mint a shared key converge on one.
+ */
+export interface E2eKeyStore {
+    readonly kind: E2eKeyStoreKind;
+    /** Where the keys live, for the boot log — a path or the keychain service. */
+    readonly describe: string;
+    read(account: string): E2eKeyRecord | undefined;
+    createExclusive(account: string, record: E2eKeyRecord): E2eKeyRecord;
+    /**
+     * Replace whatever is filed under `account`. For a person acting on their own
+     * key — unlocking it on this machine, or replacing it after a rotation. A
+     * runtime converging with its peers on a shared key wants `createExclusive`,
+     * which never clobbers the winner of that race.
+     */
+    write(account: string, record: E2eKeyRecord): void;
+    /** Forget the account. Silent when nothing is filed there. */
+    remove(account: string): void;
+}
+/**
+ * The account a scope's default key is filed under, or `null` under `stream`,
+ * where there is no default: each key is minted for one sealed stream on its
+ * grant and filed under {@link e2eStreamKeyAccount}.
+ *
+ * `host` hashes the hostname because `~/.threa` can be a home directory shared
+ * across machines, and a key that followed the home directory would put every
+ * box on one identity without the operator ever choosing that.
+ */
+export declare function e2eKeyAccount(params: {
+    scope: E2eKeyScope;
+    hostname: string;
+    instanceId: string;
+    /** Secret that identifies the bot (its API key); hashed, never stored. */
+    identitySeed: string;
+}): string | null;
+/** The account one stream's key is filed under. */
+export declare function e2eStreamKeyAccount(streamId: string): string;
+/**
+ * The account a person's own identity key is filed under, once they unlock it
+ * on this machine. Separate from the bot scopes above: this is the key the web
+ * app minted from their passphrase, and a CLI holding it reads their streams as
+ * them, not as a runtime.
+ */
+export declare function e2eUserKeyAccount(workspaceId: string, userId: string): string;
+export declare class FileKeyStore implements E2eKeyStore {
+    readonly kind: "file";
+    readonly describe: string;
+    private readonly dir;
+    constructor(opts: {
+        dir: string;
+    });
+    private path;
+    read(account: string): E2eKeyRecord | undefined;
+    /**
+     * Whether this directory already serves any key. The per-stream policy has no
+     * single account to probe for — its keys are named after streams it has not
+     * been granted yet — so store selection asks this instead.
+     */
+    hasAny(): boolean;
+    createExclusive(account: string, record: E2eKeyRecord): E2eKeyRecord;
+    write(account: string, record: E2eKeyRecord): void;
+    remove(account: string): void;
+}
+interface CommandResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+    /** The command could not be run at all (binary missing). */
+    unavailable: boolean;
+}
+export declare const KEYCHAIN_COMMAND_TIMEOUT_MS = 5000;
+export declare function runKeychainCommand(command: string, args: string[], input?: string, timeoutMs?: number): CommandResult;
+export type CommandRunner = (command: string, args: string[], input?: string) => CommandResult;
+export declare class MacKeychainStore implements E2eKeyStore {
+    readonly kind: "keychain";
+    readonly describe = "macOS keychain (service threa-e2e)";
+    private readonly exec;
+    constructor(opts?: {
+        exec?: CommandRunner;
+    });
+    read(account: string): E2eKeyRecord | undefined;
+    createExclusive(account: string, record: E2eKeyRecord): E2eKeyRecord;
+    write(account: string, record: E2eKeyRecord): void;
+    remove(account: string): void;
+}
+/**
+ * The freedesktop Secret Service, driven through `secret-tool`. `store`
+ * overwrites, so exclusivity is a read before the write and a read after it:
+ * the value that comes back is the one every process on this box will use.
+ */
+export declare class SecretServiceStore implements E2eKeyStore {
+    readonly kind: "keychain";
+    readonly describe = "Secret Service keyring (service threa-e2e)";
+    private readonly exec;
+    constructor(opts?: {
+        exec?: CommandRunner;
+    });
+    read(account: string): E2eKeyRecord | undefined;
+    createExclusive(account: string, record: E2eKeyRecord): E2eKeyRecord;
+    write(account: string, record: E2eKeyRecord): void;
+    remove(account: string): void;
+}
+export interface ResolveKeyStoreInput {
+    /** The operator's explicit choice. Unset lets an available keychain win. */
+    requested?: E2eKeyStoreKind;
+    platform: NodeJS.Platform;
+    /** Where a file store keeps its keys. */
+    dir: string;
+    /** Already-persisted key material, when found: an existing file store keeps serving it. */
+    hasExistingFileKey: boolean;
+    exec?: CommandRunner;
+}
+/**
+ * Pick the store for this machine. An explicit `keychain` that cannot run is an
+ * error rather than a quiet move to disk (INV-11), and with nothing explicit a
+ * box without a working keychain is asked to choose instead of being given one.
+ */
+export declare function resolveKeyStore(input: ResolveKeyStoreInput): E2eKeyStore;
+export interface E2eKeyringOptions {
+    store: E2eKeyStore;
+    /**
+     * The account the unscoped default key is filed under; see
+     * {@link e2eKeyAccount}. `null` selects the per-stream policy: no default
+     * key, one minted per sealed stream the bot is granted.
+     */
+    account: string | null;
+    /** Mints a fresh record when the account is empty. */
+    mint: () => Promise<E2eKeyRecord>;
+    /**
+     * A single-key file from before the keyring. When the account holds nothing
+     * and this does, the old key is adopted under the new account: its id is the
+     * address of every wrap an owner already made, so minting a fresh one instead
+     * would strand every sealed stream the runtime serves.
+     */
+    legacy?: () => E2eKeyRecord | undefined;
+    log?: (message: string) => void;
+}
+/**
+ * This runtime's keyring. `ensure()` loads or mints the default key once;
+ * `ensureForStream()` adds a stream-pinned key under the per-stream policy. The
+ * result is what rides `bot:hello` and every presence write, where the server
+ * reads it as the instance's complete set.
+ */
+export declare class E2eKeyring {
+    private readonly opts;
+    private readonly log;
+    private held;
+    private inFlight;
+    private loaded;
+    constructor(opts: E2eKeyringOptions);
+    /** The loaded keys; empty until `ensure()` resolves. */
+    get current(): HeldE2eKey[];
+    ensure(): Promise<HeldE2eKey[]>;
+    /**
+     * The key this runtime reads `streamId` with. Under the default policy that
+     * is the unscoped key, which already covers every stream, so this is a no-op.
+     * Under the per-stream policy it mints one key for this stream — the owner's
+     * next re-wrap addresses the stream key to it.
+     */
+    ensureForStream(streamId: string): Promise<HeldE2eKey[]>;
+    /**
+     * Forget this stream's key: drop it from the held set and from the store.
+     * Under the default policy the key covers every stream this runtime serves,
+     * so a revoke on one of them must leave it alone — only a key minted FOR the
+     * revoked stream is dead, and only once its wraps are gone server-side.
+     */
+    dropStream(streamId: string): E2eKeyRecord[];
+    /**
+     * The key a wrap for `streamId` must be addressed to, once `ensureForStream`
+     * has resolved. Under the default policy that is the unscoped key whatever
+     * the stream; under the per-stream policy picking the first held key would
+     * address another stream's.
+     */
+    forStream(streamId: string): HeldE2eKey | undefined;
+    /**
+     * The keyring as it rides presence. `publicKey`/`publicKeyId` carry the
+     * default key as well: a server from before the registry reads only those,
+     * and both name the same key, so a mixed-version rollout addresses one key
+     * either way. Under the per-stream policy there is no default key, so those
+     * two are omitted rather than naming a stream key an old server would
+     * register as covering everything.
+     */
+    presenceFields(): {
+        e2eKeys: {
+            keyId: string;
+            publicKey: string;
+            streamId?: string;
+        }[];
+        publicKey?: string;
+        publicKeyId?: string;
+    } | Record<string, never>;
+    /**
+     * Load or mint one account's key and fold it into the held set. Concurrent
+     * callers for the same account share one attempt: boot presence and
+     * `bot:hello` both ensure, and a grant can arrive while either is in flight,
+     * so without this they would each mint past the cache check and race the
+     * store.
+     */
+    private loadAccount;
+    private mintAccount;
+    private createRecord;
+}
+/**
+ * Read the single-key BIK file a runtime used before keyrings. Its `publicKeyId`
+ * is the address of every wrap the owner already made for this install, so the
+ * record is adopted under the configured scope rather than replaced.
+ */
+export declare function readLegacyBikFile(path: string): E2eKeyRecord | undefined;
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@threahq/bot-runtime-client",
+  "version": "0.1.0",
+  "description": "Protocol client for Threa's bot runtime: the /bot WebSocket transport (presence, claim renewal, trace steps, work nudges) with an HTTP fallback, plus the sealed-turn crypto an end-to-end-encrypted bot needs.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/threahq/threa.git",
+    "directory": "extensions/bot-runtime-client"
+  },
+  "homepage": "https://threa.io/developers",
+  "bugs": {
+    "url": "https://github.com/threahq/threa/issues"
+  },
+  "keywords": [
+    "threa",
+    "bot",
+    "agent",
+    "runtime",
+    "socket.io",
+    "e2ee"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@hpke/core": "^1.9.0",
+    "@hpke/dhkem-x25519": "^1.6.0",
+    "hash-wasm": "^4.12.0",
+    "ulid": "^2.3.0"
+  },
+  "peerDependencies": {
+    "socket.io-client": "^4.8.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/sealed-stream-client.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Read and write an end-to-end-encrypted stream over Threa's public API.
+ *
+ * The sealed-turn path in `./sealed` covers a bot answering an invocation: the
+ * backend hands it ciphertext and SSK wraps on the claim. Everything else — a
+ * CLI reading its owner's scratchpad, a bot posting into a sealed stream it was
+ * granted but was not invoked in — has to fetch the wraps itself, unwrap the
+ * stream key, and open or seal each body. That is this client: the crypto is
+ * the same module, but the keys come from the caller's own keyring and the
+ * transport is the public HTTP API.
+ *
+ * Threads inherit their root scratchpad's key and carry no wraps of their own,
+ * so every id is resolved to its root before any key work — pass a thread id
+ * and it still reads and seals correctly.
+ */
+import { type AttachmentRef, type StreamEnvelope, type WebCryptoKey } from "./crypto.js";
+import type { E2eKeyring } from "./keyring.js";
+/** One key this client can open a wrap with. */
+export interface SealedKeyIdentity {
+    /** The id wraps are addressed to — a BIK's `publicKeyId`, or a user's UIK key id. */
+    keyId: string;
+    privateKey: WebCryptoKey;
+}
+/**
+ * Where the client's private keys come from. A bot passes its runtime keyring;
+ * an interactive client passes whatever it unlocked. Called per stream because
+ * the per-stream key policy mints one key per sealed stream.
+ */
+export interface SealedKeySource {
+    keysForStream(streamId: string): Promise<SealedKeyIdentity[]>;
+}
+/** Bridge a runtime's {@link E2eKeyring} into a {@link SealedKeySource}. */
+export declare function keyringKeySource(keyring: E2eKeyring): SealedKeySource;
+/**
+ * One message from a sealed stream. `contentMarkdown` is the opened body;
+ * it is `null` exactly when this client could not open the row, and
+ * `unreadableReason` then says why — a row sealed under the pre-stream-key
+ * scheme, or a generation no key here is wrapped to. Neither is fatal for the
+ * rest of the page, so the row is reported rather than thrown.
+ */
+export interface SealedStreamMessage {
+    id: string;
+    sequence: string;
+    authorId: string;
+    authorType: string;
+    authorDisplayName?: string;
+    createdAt: string;
+    contentMarkdown: string | null;
+    attachmentRefs: AttachmentRef[];
+    unreadableReason?: string;
+}
+export interface SealedStreamPage {
+    messages: SealedStreamMessage[];
+    hasMore: boolean;
+}
+export interface SealedStreamClientOptions {
+    /** Workspace API origin, e.g. `https://eu.threa.io`. */
+    baseUrl: string;
+    apiKey: string;
+    workspaceId: string;
+    keys: SealedKeySource;
+    /**
+     * The actor id bound into outgoing message AAD. Resolved from
+     * `GET /me` when omitted, which is what a caller holding only a key knows.
+     */
+    senderId?: string;
+    fetch?: typeof globalThis.fetch;
+}
+/** The `sealed` field a message row carries in place of readable content. */
+export interface SealedMessageBody {
+    ciphertext: string;
+    envelope: StreamEnvelope;
+}
+/** What opening one {@link SealedMessageBody} produced. */
+export interface OpenedSealedBody {
+    contentMarkdown: string | null;
+    attachmentRefs: AttachmentRef[];
+    unreadableReason?: string;
+}
+/** A non-2xx from the API, carrying the `code` the wire named. */
+export declare class SealedStreamApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+export declare class SealedStreamClient {
+    private readonly opts;
+    private readonly doFetch;
+    private readonly roots;
+    private readonly ssks;
+    private readonly generations;
+    private sender?;
+    constructor(opts: SealedStreamClientOptions);
+    /**
+     * One page of decrypted messages, newest-last. `before`/`after` take the
+     * `sequence` of a message already held, exactly as the plaintext list does.
+     */
+    readMessages(streamId: string, opts?: {
+        limit?: number;
+        before?: string;
+        after?: string;
+    }): Promise<SealedStreamPage>;
+    /**
+     * Seal `contentMarkdown` under the stream key and post it. The returned
+     * `messageId` is the server's row id; `clientMessageId` is the id this client
+     * minted, bound into the body's AAD and reusable to retry the send.
+     */
+    sendMessage(streamId: string, contentMarkdown: string, opts?: {
+        attachmentRefs?: AttachmentRef[];
+        clientMessageId?: string;
+    }): Promise<{
+        messageId: string;
+        clientMessageId: string;
+    }>;
+    /**
+     * Open one sealed body for a caller that fetched the row itself — a client
+     * reading the plaintext list route, where sealed rows arrive beside an opaque
+     * placeholder. `streamId` may be the thread the row lives in; its root's key
+     * is what opens it.
+     *
+     * A body this client cannot open comes back with a null `contentMarkdown` and
+     * a reason rather than throwing, so one unreadable generation never costs the
+     * caller the rest of the page.
+     */
+    openSealedBody(streamId: string, sealed: SealedMessageBody): Promise<OpenedSealedBody>;
+    private openBody;
+    private openMessage;
+    /**
+     * The stream key for one generation. Wraps are fetched once per stream and
+     * every generation they cover is unwrapped in that pass, so a page spanning a
+     * rotation costs one round trip.
+     */
+    private streamKey;
+    /**
+     * Never cached: sealing under a stale generation after the owner rolled the
+     * key would hand the revoked generation's holders a readable message, and the
+     * send path validates only the envelope's shape.
+     */
+    private currentGeneration;
+    private loadWraps;
+    /** A thread's key lives on its root; a root resolves to itself. */
+    private resolveRoot;
+    private resolveSenderId;
+    private request;
+}