@byokit/pair 0.0.0-stage → 0.9.0

package/dist/host.d.ts

@@ -0,0 +1,214 @@
+import { type KeyPair } from './channel.ts';
+import { type LinkStream } from './stream.ts';
+export type Role = 'control' | 'view';
+/** One paired device. `key` is its static public key (base64url); `kind` is the app's own label (e.g. `browser`,
+ *  `peer`) for per-kind caps; `expires` ends its access (absent: until removed); `meta` is the app's own. */
+export type Grant = {
+    id: string;
+    key: string;
+    name: string;
+    role: Role;
+    created: number;
+    lastSeen?: number;
+    kind?: string;
+    expires?: number;
+    nextKey?: string;
+    meta?: unknown;
+};
+export type GrantStore = {
+    load(): Grant[] | Promise<Grant[]>;
+    save(grants: Grant[]): void | Promise<void>;
+    /** Notify after durable changes, including changes made by other processes. Returns an unsubscribe function.
+     *  The host serializes reloads with its own writes; notifications need not contain grants. */
+    subscribe?: (changed: () => void) => () => void;
+};
+/** Keeps completed answers across host restarts. Store `{ op, args, reply }` as passed to `put` unchanged;
+ *  `args` is JSON.stringify of the request arguments (or null). A missing answer after a crash may run again.
+ *  `drop` without keys drops every answer for that device. */
+export type AnswerStore = {
+    get(device: string, key: string): unknown | Promise<unknown>;
+    put(device: string, key: string, answer: object): void | Promise<void>;
+    drop(device: string, keys?: string[]): void | Promise<void>;
+};
+export type LinkRequest = {
+    op: string;
+    args?: unknown;
+    key?: string;
+};
+/** What the person at the host is asked to approve. `words` are on the device's screen too. */
+export type PairRequest = {
+    name: string;
+    role: Role;
+    words: string;
+    how: 'scan' | 'code';
+    kind?: string;
+    lifetime?: number;
+    meta?: unknown;
+};
+/** Anything shaped like a browser WebSocket or a `ws` one. */
+export type Socket = {
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, fn: (e: any) => void): void;
+};
+/** How a grant is made: its role, and optionally its kind, how long its access lasts (ms) and the app's own data. */
+export type GrantTerms = {
+    role: Role;
+    kind?: string;
+    lifetime?: number;
+    meta?: unknown;
+};
+export type HostOptions = {
+    keys: KeyPair;
+    /** The name devices show for this computer. */
+    name: string;
+    /** Answers a device's request. Runs on the host, with the host's credentials; the device only gets the answer. */
+    handle: (req: LinkRequest, device: Grant) => unknown;
+    /** Asks the person at the host whether this device may join; nothing is stored until it says yes. */
+    confirm: (p: PairRequest) => boolean | Promise<boolean>;
+    /** Takes a stream a device opened with `link.stream(op, args)` (a terminal pane, a tunnelled connection, a call):
+     *  set `onData` and `onEnd`, `write`, `end`. The stream opens before this handler runs; a thrown
+     *  `PublicLinkError` ends it with a message for the device, while other errors go to `onError` and end it with
+     *  `failed`. `device` is the authenticated grant. Without this, devices are told this host has no streams. */
+    stream?: (s: LinkStream, req: LinkRequest, device: Grant) => void | Promise<void>;
+    /** Decides every request or stream before the app handles it. When absent, control devices may do anything
+     *  and view-only devices only what `canView` allows. */
+    allow?: (req: LinkRequest, device: Grant) => boolean | Promise<boolean>;
+    /** Which requests and streams a view-only device may open when there is no `allow`. Default: none. */
+    canView?: (req: LinkRequest) => boolean;
+    /** First authenticated socket up / last socket down per grant. Exceptions go to onError. */
+    onConnection?: (grant: Grant, online: boolean) => void;
+    /** After durable removal, expiry or authority change; never a socket drop. Called even for offline grants.
+     *  Access/streams are already invalidated. Removal awaits returned privacy cleanup; failure never restores access. */
+    onGrantRemoved?: (grant: Grant, why: 'revoked' | 'expired' | 'changed') => void | Promise<void>;
+    /** Opt-in app data sent inside sealed ready, on pairing and reconnect. Never implicitly exposes Grant.meta. */
+    deviceMeta?: (grant: Grant) => unknown;
+    onError?: (error: unknown) => void;
+    grants?: GrantStore;
+    answers?: AnswerStore;
+    maxDevices?: number;
+    /** At most this many devices of each kind, e.g. `{ peer: 16 }`. */
+    caps?: Record<string, number>;
+    /** New handshakes allowed per minute, in all and per `peer` given to `accept`. Default 300 and 30. */
+    handshakes?: {
+        perMinute?: number;
+        perPeer?: number;
+    };
+    /** How long a pairing code, and a person's answer, may take. At most (and by default) five minutes. */
+    pairMs?: number;
+    /** The clock, for tests. */
+    now?: () => number;
+};
+/** What a 0.3 host understands beyond 0.1, told to devices in `ready`. */
+export declare const FEATURES: string[];
+export declare class Host {
+    readonly keys: KeyPair;
+    /** This host's address on a relay. */
+    readonly id: string;
+    private opts;
+    private grants;
+    private store?;
+    private tickets;
+    private codes;
+    private tries;
+    private live;
+    private expiryTimers;
+    private answered;
+    private answerWork;
+    private changes;
+    private unsubscribe?;
+    private stopped;
+    private recent;
+    private constructor();
+    static open(opts: HostOptions): Promise<Host>;
+    private now;
+    private get pairMs();
+    private ended;
+    private currentGrant;
+    private admitGrant;
+    private change;
+    private save;
+    private report;
+    private answerTask;
+    private drop;
+    private presence;
+    private addLive;
+    private removeLive;
+    private watchExpiry;
+    private endLive;
+    /** Every grant change goes through here, one at a time: store first, then memory, then the live sockets. */
+    private transition;
+    /** Re-read the durable authority without writing it back. Removed/changed grants close their sockets.
+     *  A failed read leaves memory untouched and rejects; subscribed failures also reach onError. */
+    reload(): Promise<void>;
+    private pending;
+    /** A QR's text for one device. `urls` are where a device can reach this host (direct `ws://`, or a relay's
+     *  `wss://…/link/v1/<id>`); `base` makes it a link a browser can open. Single use, gone after `pairMs`. */
+    offer(o: GrantTerms & {
+        urls: string[];
+        base?: string;
+    }): {
+        text: string;
+        expires: number;
+    };
+    /** A QR-sized offer: the same secret a typed code carries (same single use, life, words and approval, through
+     *  one code entry), plus the addresses to try, packed binary. No browser-link form: links keep `offer`. */
+    compactOffer(o: GrantTerms & {
+        urls: string[];
+    }): {
+        text: string;
+        code: string;
+        expires: number;
+    };
+    /** A code a person types on the device instead of scanning. Single use, gone after `pairMs`. */
+    code(o: GrantTerms): {
+        code: string;
+        expires: number;
+    };
+    /** A 57-character typed offer that pins this machine's key. Use the whole code with `pairWithCode`;
+     *  addresses come separately (e.g. relay `findHost`). Same approval, single use and expiry as `code`. */
+    shortCode(o: GrantTerms): {
+        code: string;
+        expires: number;
+    };
+    /** Withdraws every open QR and code. */
+    stopPairing(): void;
+    devices(): (Grant & {
+        online: boolean;
+    })[];
+    /** Adds a device this app already trusts some other way: for moving devices paired under an older protocol onto
+     *  this one without pairing again. Only call it with a key that arrived over an authenticated channel. */
+    enrol(g: GrantTerms & {
+        key: Uint8Array;
+        name: string;
+    }): Promise<Grant>;
+    setMeta(id: string, meta: unknown): Promise<void>;
+    /** Removes a device: its grant goes, its open connections close, and its key is refused from now on. */
+    revoke(id: string, why?: 'revoked' | 'ended'): Promise<void>;
+    /** An event for every connected device (or those `to` picks). */
+    broadcast(e: unknown, to?: (g: Grant) => boolean): void;
+    /** One WebSocket, straight from a device. `peer` (e.g. its IP address) lets the host slow down one noisy source. */
+    accept(ws: Socket, o?: {
+        peer?: string;
+    }): void;
+    /** One WebSocket to a relay that carries many devices' connections. Each relay message is `{c, f}` (connection id,
+     *  one frame, exactly as a device sent it or should get it) or `{c, end: code}`. The relay sees only that. */
+    relay(ws: Socket): void;
+    close(): void;
+    private sealed;
+    private out;
+    /** What the device hears when the app's stream code throws: a `PublicLinkError`'s message, else `failed`. */
+    private reason;
+    private take;
+    private wrong;
+    /** A sliding one-minute window, in all and per peer; checked before any key agreement is spent on a stranger. */
+    private admit;
+    private checkLifetime;
+    private grant;
+    private connection;
+    private openStream;
+    private acknowledge;
+    private request;
+    private admitRequest;
+    private run;
+}