@termfleet/core 0.1.0

package/dist/provider-access-token.js

@@ -0,0 +1,77 @@
+import { normalizeProviderOrigin } from "./contracts/provider-url.js";
+// A provider access token: a short-lived, org-scoped bearer the registry mints (only
+// for a user entitled to the provider's owning org) and a provider trusts in place of
+// a bare session. Shared by the standalone registry and the Cloud Worker so the wire
+// format and verification are identical. HS256 over Web Crypto (available in Node 20+
+// and Workers). The registry holds the signing secret; a provider verifies via the
+// registry's /provider-tokens/verify endpoint (it never holds the secret).
+// Short-lived by design: a leaked token is only useful for minutes, and the browser/
+// CLI re-mints transparently. Shared so the worker and standalone registry agree.
+export const PROVIDER_ACCESS_TOKEN_DURATION_MS = 10 * 60 * 1000;
+export async function signProviderAccessToken(payload, secret) {
+    const signingInput = `${base64UrlJson({ alg: "HS256", typ: "TFPT" })}.${base64UrlJson(payload)}`;
+    return `${signingInput}.${await hmacSha256(signingInput, secret)}`;
+}
+// Verifies signature, structure, and audience and returns the payload. Throws on any
+// malformation/forgery. Expiry is the caller's to check (it owns the clock + the
+// error shape). Constant-time signature compare.
+export async function verifyProviderAccessTokenPayload(token, secret) {
+    if (!token) {
+        throw new Error("Provider access token is required.");
+    }
+    const parts = token.split(".");
+    if (parts.length !== 3 || !parts[0] || !parts[1] || !parts[2]) {
+        throw new Error("Provider access token is malformed.");
+    }
+    const signingInput = `${parts[0]}.${parts[1]}`;
+    if (!constantTimeEqual(parts[2], await hmacSha256(signingInput, secret))) {
+        throw new Error("Provider access token signature is invalid.");
+    }
+    const payload = JSON.parse(base64UrlDecode(parts[1]));
+    if (payload.aud !== "termfleet-provider"
+        || typeof payload.provider !== "string"
+        || typeof payload.sub !== "string"
+        || typeof payload.exp !== "number"
+        || typeof payload.iat !== "number"
+        || (payload.org !== undefined && typeof payload.org !== "string")) {
+        throw new Error("Provider access token payload is malformed.");
+    }
+    return {
+        aud: payload.aud,
+        exp: payload.exp,
+        iat: payload.iat,
+        ...(payload.org ? { org: payload.org } : {}),
+        provider: normalizeProviderOrigin(payload.provider),
+        sub: payload.sub
+    };
+}
+function base64UrlJson(value) {
+    return base64UrlEncodeBytes(new TextEncoder().encode(JSON.stringify(value)));
+}
+function base64UrlEncodeBytes(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64UrlDecode(value) {
+    const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+    const binary = atob(padded);
+    return new TextDecoder().decode(new Uint8Array([...binary].map((char) => char.charCodeAt(0))));
+}
+async function hmacSha256(value, secret) {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { hash: "SHA-256", name: "HMAC" }, false, ["sign"]);
+    const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(value));
+    return [...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    let mismatch = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        mismatch |= left.charCodeAt(index) ^ right.charCodeAt(index);
+    }
+    return mismatch === 0;
+}

package/dist/provider-client.d.ts

@@ -0,0 +1,152 @@
+import type { AgentWindowCreateOptions, AgentWindowCreateResult } from "./agent-launch.js";
+import type { AgentProvider, AgentSessionIndexPage } from "./agent-session-index.js";
+import type { AgentSessionDetails } from "./agent-session.js";
+import type { AuthSessionResource, AuthSignInResponse } from "./contracts/auth.js";
+import type { ProviderDirectoryList, ProviderFileStat, ProviderFileWriteResult } from "./contracts/files.js";
+import type { RegistryProviderRecord } from "./contracts/registry.js";
+import type { LifecycleSnapshot } from "./session-lifecycle.js";
+import type { Bounds, OrphanSessionPruneResult, ProviderHealth, ProviderRef, ProviderSnapshot, TerminalEffectKind, TerminalThemeProfile } from "./types.js";
+import { type Socket } from "socket.io-client";
+import { type ProviderUrlResolver } from "./provider-url-resolver.js";
+export type DockerWorkerStartOptions = Partial<RegistryProviderRecord> & {
+    terminalThemeProfile?: TerminalThemeProfile;
+};
+export type ProviderSettingsUpdate = {
+    terminalThemeProfile?: TerminalThemeProfile;
+};
+type CommandAck<T> = {
+    ok?: boolean;
+    error?: string;
+    result?: T;
+    snapshot?: ProviderSnapshot;
+};
+export type ProviderClientOptions = {
+    authToken?: () => string | undefined;
+    urlResolver?: ProviderUrlResolver;
+};
+export declare class ProviderClient {
+    readonly ref: ProviderRef;
+    private readonly authToken?;
+    private readonly urls;
+    private readonly apiBase;
+    private socket?;
+    private readonly agentSubscriptions;
+    private agentListenersSocket?;
+    constructor(ref: ProviderRef, options?: ProviderClientOptions);
+    health(): Promise<ProviderHealth>;
+    snapshot(): Promise<ProviderSnapshot>;
+    updateProviderSettings(settings: ProviderSettingsUpdate): Promise<{
+        result: unknown;
+        snapshot?: ProviderSnapshot;
+    }>;
+    lifecycle(): Promise<LifecycleSnapshot>;
+    pruneOrphanSessions(): Promise<OrphanSessionPruneResult>;
+    registryProviders(options?: {
+        authToken?: string;
+    }): Promise<RegistryProviderRecord[]>;
+    registerLocalProvider(provider: RegistryProviderRecord): Promise<RegistryProviderRecord>;
+    unregisterLocalProvider(baseUrl: string): Promise<RegistryProviderRecord>;
+    registerSharedProvider(provider: RegistryProviderRecord, options: {
+        authToken: string;
+    }): Promise<RegistryProviderRecord>;
+    unregisterSharedProvider(baseUrl: string, options: {
+        authToken: string;
+    }): Promise<RegistryProviderRecord>;
+    startDockerWorker(options?: DockerWorkerStartOptions): Promise<RegistryProviderRecord>;
+    startLocalProvider(options: {
+        kind: "iterm" | "virtual-tmux" | "wezterm";
+        label?: string;
+    }): Promise<RegistryProviderRecord>;
+    signInToRegistry(identifier: string, password: string): Promise<AuthSignInResponse>;
+    registrySession(authToken: string): Promise<AuthSessionResource>;
+    signOutOfRegistry(authToken: string): Promise<unknown>;
+    switchRegistryOrganization(organizationId: string, options: {
+        authToken: string;
+    }): Promise<AuthSessionResource>;
+    captureTerminal(terminalId: string, lines?: number, options?: {
+        preserveEscapes?: boolean;
+    }): Promise<{
+        content: string;
+    }>;
+    getAgentSession(agent: AgentProvider, sessionId: string, options?: {
+        cwd?: string;
+    }): Promise<AgentSessionDetails>;
+    getAgentSubagentSession(sessionId: string, agentId: string): Promise<AgentSessionDetails>;
+    listAgentSessions(options?: {
+        cursor?: string | null;
+        limit?: number;
+        query?: string;
+    }): Promise<AgentSessionIndexPage>;
+    connect(): Socket;
+    disconnect(): void;
+    onSnapshot(handler: (snapshot: ProviderSnapshot) => void): () => void;
+    onAgentSession(sessionId: string, handlers: {
+        error?: (message: string) => void;
+        update: (details: AgentSessionDetails) => void;
+    }, options?: {
+        cwd?: string;
+    }): () => void;
+    private wireAgentSessionListeners;
+    private subscribeAgentSession;
+    createWindow<T = unknown>(options?: {
+        cwd?: string;
+        filesystemId?: string;
+        kind?: "terminal" | "folder" | "file" | "iframe";
+        name?: string;
+        path?: string;
+        terminalId?: string;
+        src?: string;
+    }): Promise<CommandAck<T>>;
+    createAgentWindow(options: AgentWindowCreateOptions, clientOptions?: {
+        timeoutMs?: number;
+    }): Promise<CommandAck<AgentWindowCreateResult>>;
+    moveWindow<T = unknown>(id: number, bounds: Bounds): Promise<CommandAck<T>>;
+    closeWindow<T = unknown>(id: number): Promise<CommandAck<T>>;
+    sendToSession<T = unknown>(agentSessionId: string, data: string, options?: {
+        submitMode?: "retry" | "single";
+    }): Promise<CommandAck<T>>;
+    closeSession<T = unknown>(agentSessionId: string): Promise<CommandAck<T>>;
+    resizeDisplay<T = Bounds>(bounds: Bounds): Promise<CommandAck<T>>;
+    sendTerminalInput<T = unknown>(terminalId: string, data: string, options?: {
+        breakGlass?: boolean;
+        submitMode?: "retry" | "single";
+    }): Promise<CommandAck<T>>;
+    sendLine<T = unknown>(terminalId: string, line: string, options?: {
+        breakGlass?: boolean;
+        submitMode?: "retry" | "single";
+    }): Promise<CommandAck<T>>;
+    setTerminalEffect<T = unknown>(terminalId: string, kind: TerminalEffectKind, options?: {
+        durationMs?: number;
+    }): Promise<CommandAck<T>>;
+    listDirectory(terminalId: string, path: string): Promise<ProviderDirectoryList>;
+    listDirectoryByFilesystem(filesystemId: string, path: string): Promise<ProviderDirectoryList>;
+    readFile(terminalId: string, path: string): Promise<Buffer>;
+    readFileByFilesystem(filesystemId: string, path: string): Promise<Buffer>;
+    statFile(terminalId: string, path: string): Promise<ProviderFileStat>;
+    statFileByFilesystem(filesystemId: string, path: string): Promise<ProviderFileStat>;
+    writeFile(terminalId: string, path: string, data: Buffer, options?: {
+        mkdirs?: boolean;
+        mode?: string;
+    }): Promise<ProviderFileWriteResult>;
+    writeFileByFilesystem(filesystemId: string, path: string, data: Buffer, options?: {
+        mkdirs?: boolean;
+        mode?: string;
+    }): Promise<ProviderFileWriteResult>;
+    private postJson;
+    private patchJson;
+    private writeJson;
+    private command;
+    private fetchProviderUrl;
+    private readAuthToken;
+}
+export declare function providerRefFromUrl(value: string, label?: string): ProviderRef;
+export declare function resolveMachineId(record: {
+    baseUrl: string;
+    instanceId?: string;
+}): string;
+export declare function machineLayoutKeyForId(machineId: string): string;
+export declare function machineLayoutKey(record: {
+    baseUrl: string;
+    instanceId?: string;
+}): string;
+export {};