@byokit/pair 0.0.0-stage → 0.9.0

package/dist/device.d.ts

@@ -0,0 +1,177 @@
+import { type KeyPair } from './channel.ts';
+import type { Role } from './host.ts';
+import { type LinkStream } from './stream.ts';
+/** What a device keeps (in secure storage: it holds the device's secret key). `nextSecretKey` is only there while
+ *  a rekey is under way. */
+export type DeviceGrant = {
+    v: 1;
+    secretKey: string;
+    nextSecretKey?: string;
+    pendingUntil?: number;
+    host: string;
+    hostName: string;
+    meta?: unknown;
+    urls: string[];
+    device: {
+        id: string;
+        name: string;
+        role: Role;
+    };
+};
+export type DeviceStore = {
+    save(g: DeviceGrant): void | Promise<void>;
+    clear(): void | Promise<void>;
+};
+export type LinkStatus = 'connecting' | 'online' | 'offline' | 'refused' | 'removed';
+type WebSocketLike = {
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    binaryType?: string;
+    onopen: any;
+    onmessage: any;
+    onclose: any;
+    onerror: any;
+};
+/** `resolve` runs before each connection and returns the address to dial: e.g. open an SSH tunnel to the host and
+ *  return `ws://127.0.0.1:<port>/…`. The grant keeps the original address. */
+export type Dial = {
+    WebSocket?: new (url: string) => WebSocketLike;
+    timeoutMs?: number;
+    resolve?: (url: string) => string | Promise<string>;
+};
+/** Every way the link can fail, in words a person can act on. */
+export declare const LINK_WORDS: {
+    readonly unreachable: "Can't reach your computer. Check it's on and connected.";
+    readonly 'wrong-host': "Something other than your computer answered, so this device didn't connect.";
+    readonly 'wrong-code': "That code didn't match. Check it, or show a new one on your computer.";
+    readonly expired: "That pairing code has run out. Show a new one on your computer.";
+    readonly declined: "Your computer said no to this device.";
+    readonly full: "Your computer has all the devices it allows. Remove one there first.";
+    readonly 'not-paired': "Your computer doesn't know this device any more. Pair it again.";
+    readonly removed: "This device was removed on your computer.";
+    readonly 'view-only': "This device can watch but not make changes.";
+    readonly timeout: "Your computer didn't answer in time.";
+    readonly failed: "Your computer couldn't do that.";
+    readonly busy: "Your computer is still catching up. Try again in a moment.";
+    readonly stopped: "This link is stopped. Try connecting again.";
+    readonly 'not-supported': "The app on your computer can't do this yet. Update it there.";
+    readonly ended: "This device's access has run out. Pair it again on your computer.";
+    readonly 'not-allowed': "This device isn't allowed to do that.";
+    readonly 'too-late': "That reached your computer too late, so it wasn't done.";
+    readonly unsupported: "Your computer needs an update for that.";
+};
+export type LinkProblem = keyof typeof LINK_WORDS;
+/** A failure with a plain `message` and a `code` for the app. `sealed` means the host said it inside the encrypted
+ *  channel, so it is really the host speaking; anything else could come from whoever is on the network. */
+export declare class LinkError extends Error {
+    code: LinkProblem;
+    sealed: boolean;
+    constructor(code: LinkProblem, sealed?: boolean);
+}
+export declare class PublicLinkError extends LinkError {
+    constructor(message: string);
+}
+type PairOptions = Dial & {
+    name: string;
+    onWords: (w: string) => void;
+    key?: KeyPair;
+};
+/** The grant a scanned code will become, to keep in secure storage *before* pairing. If the app dies while the person
+ *  at the host decides, a `DeviceLink` made from it later connects once the host has said yes (or learns it said no),
+ *  instead of leaving the host holding a grant for a key nobody has. Pass its key to `pairWithOffer`, or let
+ *  `pairWithOffer`'s `onPending` hand it over. A compact offer carries no host key: it needs `host`, the key the code
+ *  handshake authenticated (`onPending` passes it). For a version 1 offer, a different `host` is refused. */
+export declare function pendingGrant(scanned: string, o: {
+    name: string;
+    key?: KeyPair;
+    host?: string;
+}): DeviceGrant;
+type OfferOptions = PairOptions & {
+    /** Keep this pending grant before the host can approve this device (see `pendingGrant`). A compact offer calls it
+     *  once the host proved it holds the code, before this device's key and name reach it; a throw stops pairing there. */
+    onPending?: (g: DeviceGrant) => void | Promise<void>;
+};
+/** A scanned QR (or opened pairing link) in, a grant out, once the person at the host says yes. `onWords` gets the
+ *  two words to show while they decide. Tries each address in the code until one answers. A compact offer pairs
+ *  like a typed code over the packed addresses: same single use, life, words and approval; the host key it pins is
+ *  the one the code handshake authenticated, handed to `onPending` before the host learns this device. */
+export declare function pairWithOffer(scanned: string, o: OfferOptions): Promise<DeviceGrant>;
+/** A typed code in, a grant out. `Host.shortCode` also pins the machine key before sharing the device identity.
+ *  `url` is an untrusted address, e.g. from relay `findHost`; only the full code authenticates the host. */
+export declare function pairWithCode(url: string, typed: string, o: PairOptions): Promise<DeviceGrant>;
+export type LinkOptions = Dial & {
+    store?: DeviceStore;
+    onEvent?: (e: unknown) => void;
+    onStatus?: (s: LinkStatus) => void;
+    onError?: (e: unknown) => void;
+    /** How often to check a quiet connection is still there (default 20 s); it is dropped after two silent rounds. */
+    pingMs?: number;
+    /** Requests waiting at once before new ones are refused as busy (default 1000, what a host keeps per device). */
+    maxPending?: number;
+};
+export type RequestOptions = {
+    /** Give up waiting after this long. The host may still have done it; a retry is a new request. */
+    timeoutMs?: number;
+    /** A clock time (ms) after which the host must not start it. */
+    notValidAfter?: number;
+};
+/** The device's live link: connects, reconnects forever with backoff, resends unanswered requests after a reconnect. */
+export declare class DeviceLink {
+    grant: DeviceGrant;
+    status: LinkStatus;
+    private o;
+    private conn;
+    private streams;
+    private features;
+    private pending;
+    private n;
+    private tries;
+    private stopped;
+    private wake;
+    private connecting;
+    private readonly session;
+    private fresh;
+    private ack;
+    private received;
+    private storing;
+    private waiting;
+    private heard;
+    private pingId;
+    constructor(grant: DeviceGrant, o?: LinkOptions);
+    private set;
+    private report;
+    private persist;
+    private receivedReply;
+    private connect;
+    private attempt;
+    private lost;
+    /** A half-open socket (the phone changed networks) looks alive forever; a ping it never answers shows it isn't.
+     *  A tick that fires long after it was due means this device's own timers were frozen (an app in the background,
+     *  a hidden tab), not that the host went quiet: no ping went out, so none came back. */
+    private ping;
+    private sendPending;
+    private settle;
+    private again;
+    /** The socket is gone: so are its streams. */
+    private drop;
+    private message;
+    private removed;
+    /** Asks the host to do `op`. Waits through reconnects (or until `timeoutMs`); resolves only with the host's answer. */
+    request(op: string, args?: unknown, o?: RequestOptions): Promise<unknown>;
+    /** Opens a duplex stream that the host's `stream` handler takes: a terminal pane, a tunnelled connection, a call.
+     *  Only while `online`. A stream ends when its connection drops (`onEnd('unreachable')`); open it again on the next
+     *  `online`. Host permission refusals reject; errors from the app handler end an opened stream via `onEnd`. */
+    stream(op: string, args?: unknown): Promise<LinkStream>;
+    /** Another address to try, e.g. one found on the home network. A wrong host there simply fails its handshake. */
+    addUrl(url: string): void;
+    private answer;
+    /** Moves this device to a fresh key. The new key is stored before the host hears of it, and the old one keeps working
+     *  until the new one has connected, so a crash at any point leaves a key that works. */
+    rekey(): Promise<void>;
+    /** Asks the computer to forget this device, then forgets it locally once the computer confirms. */
+    unpair(): Promise<void>;
+    /** After `refused` or `offline`: try again now. */
+    retry(): void;
+    stop(): void;
+}
+export {};