hyperbrane 0.1.0

package/dist/portal-gateway/upstream.d.ts

@@ -0,0 +1,157 @@
+/**
+ * An upstream: a service a gateway holds a credential for, described as data (adapted from v2's
+ * UpstreamDef). SDK clients define upstreams in TypeScript with `defineUpstream`; the definition
+ * is plain JSON, sent to the gateway and applied there by generic code that knows nothing about
+ * any particular upstream.
+ *
+ * The secret never reaches a dimension. Dimensions hold fakes, shaped like the real tokens so their
+ * clients accept them, and the gateway replaces them in transit. Clients sign in from dimensions as
+ * they normally would: the first sign-in goes to the upstream and the gateway keeps the tokens; once
+ * it holds them, it completes every later sign-in itself (see OAuthMode.tokenUrl and `answers`).
+ *
+ * Credentials are scoped to the gateway: one per upstream, used for every dimension with a portal
+ * to it. Switching accounts means deleting the gateway's credential, so the next sign-in goes to
+ * the upstream again.
+ */
+export type UpstreamDefinition = {
+    name: string;
+    /** At least one. The gateway swaps the fakes of every mode that has a credential. */
+    modes: {
+        oauth?: OAuthMode;
+        apiKey?: ApiKeyMode;
+    };
+};
+type ModeBase = {
+    /**
+     * Requests to these hosts get the credential. Matched on host alone: v1 also matched the
+     * user-agent, and a client changing its user-agent silently stopped getting its token.
+     */
+    hosts: string[];
+    /** Where the credential goes on a matching request, replacing any fake the client sent. */
+    present: {
+        header: string;
+        scheme?: "Bearer";
+    } | {
+        query: string;
+    };
+    /** What to force onto every matching request, whatever the client sent. */
+    force?: {
+        /** Retarget the request, e.g. "https://api.internal:8443". */
+        target?: string;
+        /** Prefix prepended to the request path, so dimensions needn't know where the API is mounted. */
+        path?: string;
+        /** Query params the client doesn't get to choose. */
+        query?: Record<string, string>;
+        /** Headers the client never sees the values of. */
+        headers?: Record<string, string>;
+    };
+};
+export type OAuthMode = ModeBase & {
+    /**
+     * The token endpoint. Until the gateway holds a credential, requests go through and the response
+     * is kept as the credential, reaching the dimension with fakes in place of the tokens. From then
+     * on the gateway answers them itself from that credential: a sign-in (whatever code it carries)
+     * and a refresh made with a fake refresh token. A client's refresh goes upstream, replayed with the
+     * real refresh token (its encoding, client id, scope, User-Agent: nothing about refreshing needs
+     * declaring); refresh tokens rotate and every dimension shares the credential, so refreshes are
+     * made one at a time and those arriving together share the result. Every client holds the same
+     * fakes, so all of them get the new tokens. A sign-in to an expired credential refreshes it first;
+     * one the gateway can't refresh (no client has refreshed yet, or upstream refuses) counts as none,
+     * and the sign-in goes to the upstream again.
+     */
+    tokenUrl: string;
+    /** What the fakes look like, per token in the token response. */
+    fakes: {
+        access: FakeShape;
+        refresh: FakeShape;
+        id?: FakeShape;
+    };
+    /** Other secrets the token endpoint returns, dropped before the response reaches the dimension. */
+    strip?: {
+        fields?: string[];
+        headers?: string[];
+    };
+    /**
+     * Other sign-in steps the gateway answers itself once it holds a credential, so the client's
+     * sign-in completes without a browser: e.g. the endpoint a device flow polls until approved.
+     */
+    answers?: {
+        url: string;
+        status?: number;
+        json: unknown;
+    }[];
+};
+/**
+ * The gateway holds any number of named keys for the upstream and gives each its own fake. A request
+ * goes out with the real key its fake maps to, so a dimension can use different keys side by side
+ * (one per process, per config entry, ...). A value that isn't one of the fakes is left as it is.
+ */
+export type ApiKeyMode = ModeBase & {
+    fake: FakeShape;
+};
+/**
+ * `prefix`: the fake is the prefix plus random characters, as long as the real value (clients check
+ * both; claude blanks a credentials file whose token it doesn't recognise).
+ * `jwt`: the fake carries the real token's header and claims with a signature that can't verify,
+ * for clients that read claims (codex decides when to refresh from `exp`). It's re-issued whenever
+ * the real token changes, so its claims keep tracking the real ones.
+ */
+export type FakeShape = {
+    prefix: string;
+} | {
+    jwt: true;
+};
+/**
+ * What the gateway keeps for an upstream, in its state directory, one file per writer:
+ * credentials/<upstream>.oauth.json (the gateway, as it captures and refreshes tokens) and
+ * credentials/<upstream>.api-keys.json (the service).
+ */
+export type OAuthCredential = {
+    access: string;
+    refresh?: string;
+    id?: string;
+    /** Epoch ms. */
+    expiresAt?: number;
+    refreshExpiresAt?: number;
+    scopes?: string[];
+    /** Epoch ms of the last sign-in or refresh. */
+    lastRefresh: number;
+    /**
+     * Issued once and kept across refreshes and sign-ins, so every dimension's copy stays valid. A
+     * prefix fake is recognised by its value; a JWT fake by its signature, since its header and
+     * claims follow the real token's, so a stale copy still maps to the current token.
+     */
+    fakes: {
+        access: StoredFake;
+        refresh?: StoredFake;
+        id?: StoredFake;
+    };
+    /** The last token response minus stripped fields; the gateway answers sign-ins and refreshes from it. */
+    response: Record<string, unknown>;
+    /**
+     * The last refresh request a client made, minus its refresh token: the gateway replays it with the
+     * real one, so upstream sees the CLI's own request (User-Agent null when the client sent none).
+     */
+    refreshRequest?: {
+        contentType: string;
+        userAgent: string | null;
+        fields: Record<string, unknown>;
+    };
+};
+export type StoredFake = {
+    value: string;
+} | {
+    jwtSignature: string;
+};
+export type ApiKeyCredential = {
+    /** Key name -> key. */
+    keys: Record<string, ApiKey>;
+};
+/** `fake` is issued once and kept, so a dimension's configuration stays valid when the key changes. */
+export type ApiKey = {
+    key: string;
+    fake: string;
+};
+/** Declares an upstream; checks the shape at compile time and returns it unchanged. */
+export declare function defineUpstream(definition: UpstreamDefinition): UpstreamDefinition;
+export {};

package/dist/portal-gateway/upstream.js

@@ -0,0 +1,4 @@
+/** Declares an upstream; checks the shape at compile time and returns it unchanged. */
+export function defineUpstream(definition) {
+    return definition;
+}

package/dist/sandbox/api.d.ts

@@ -0,0 +1,184 @@
+export type RunCommandOptions = {
+    /** Sandbox path; defaults to the sandbox root. */
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string | Uint8Array;
+};
+export type RunCommandResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type SandboxFileInfo = {
+    type: "file" | "directory" | "other";
+    uid: number;
+    gid: number;
+};
+export type SandboxFetchInit = {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array<ArrayBuffer>;
+    /** Sandbox path of a unix socket to send the request over (e.g. the docker API socket). */
+    unix?: string;
+    signal?: AbortSignal;
+    /**
+     * Idle timeout in milliseconds: the request fails once nothing has been sent or received for this
+     * long. `false` disables it, for streams that can stay quiet indefinitely. Defaults to the backend's.
+     */
+    timeout?: number | false;
+};
+/** A stream connection to a unix socket inside a sandbox (see Sandbox.connect). */
+export type SandboxConnection = {
+    write(data: Uint8Array): void;
+    /** Receives every chunk read from the socket, in order. */
+    onData(listener: (data: Uint8Array) => void): void;
+    /** Resolves once the connection is closed, by either side or by an error. */
+    closed: Promise<void>;
+    close(): void;
+};
+/** What an accessible endpoint forwards to, inside the sandbox. */
+export type SandboxEndpointTarget = {
+    port: number;
+} | {
+    unix: string;
+};
+/**
+ * What a client must present to an accessible endpoint. There is deliberately no unauthenticated
+ * variant: every endpoint requires one of these.
+ */
+export type SandboxEndpointCredentials = 
+/** `Authorization: Bearer <token>`. */
+{
+    scheme: "bearer";
+    token: string;
+}
+/** `Authorization: Basic ...`; browsers prompt for it on their own. */
+ | {
+    scheme: "basic";
+    username: string;
+    password: string;
+}
+/**
+ * Logged in with exe.dev, as a user the VM is shared with; exe.dev's proxy checks it (exeDevAuth.ts).
+ * The login is per port: a browser that isn't logged in on the endpoint's goes through `loginUrl`
+ * first (exeDevLoginUrl in agent/session/workerSseConnection.ts).
+ */
+ | {
+    scheme: "exe.dev";
+    loginUrl: string;
+};
+export type SandboxEndpointScheme = SandboxEndpointCredentials["scheme"];
+export type SandboxEndpointRequest = {
+    target: SandboxEndpointTarget;
+    /** Required: the endpoint is never open to unauthenticated clients. */
+    scheme: SandboxEndpointScheme;
+    /** Port the endpoint listens on; a free one (that its auth allows) if omitted. */
+    port?: number;
+    /**
+     * "http" (the default): the target speaks HTTP, and requests go through to it. "sse": the target
+     * is a stream socket speaking lines of text (an agent worker's JSON-RPC); each `GET /` opens a
+     * connection to it and streams its lines back as server-sent events, and `POST /<connection>`
+     * writes the request body to it (see endpointProxy.ts).
+     */
+    transport?: "http" | "sse";
+    /**
+     * Web origins (e.g. "https://app.example.com") whose pages may call the endpoint from a browser:
+     * the proxy answers their CORS preflights and lets them read "sse" responses. None by default.
+     */
+    allowedOrigins?: string[];
+};
+export type SandboxEndpoint = {
+    id: string;
+    /**
+     * Where the client reaches the endpoint, directly over the network (not through the backend's own
+     * connection), at the host the sandbox was created with.
+     */
+    url: string;
+    /** What the client presents; requests without it are refused before reaching the target. */
+    credentials: SandboxEndpointCredentials;
+    /** As requested: fixed for the endpoint's life. */
+    allowedOrigins: string[];
+};
+/**
+ * Paths are sandbox paths: relative or absolute, both resolved against the sandbox root.
+ * Operations that report a missing path throw SandboxNotFoundError, whatever the backend.
+ */
+export interface SandboxFileOperations {
+    /** Throws SandboxNotFoundError if missing. */
+    readFile(path: string): Promise<Uint8Array>;
+    /** Atomically replaces the file (readers never see partial content). Creates missing parent directories. */
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    /**
+     * Writes the file only if it doesn't exist yet; returns false if it does. Atomic across concurrent
+     * callers and never exposes partial content. Creates missing parent directories.
+     */
+    writeFileExclusive(path: string, data: string | Uint8Array): Promise<boolean>;
+    /** No-op if missing. */
+    removeFile(path: string): Promise<void>;
+    /** Creates missing parents; no-op if it exists. */
+    createDirectory(path: string): Promise<void>;
+    /** Removes the directory and everything in it. No-op if missing. */
+    removeDirectory(path: string): Promise<void>;
+    /** Entry names, unsorted. Throws SandboxNotFoundError if missing. */
+    listDirectory(path: string): Promise<string[]>;
+    /** Throws SandboxNotFoundError if missing. */
+    stat(path: string): Promise<SandboxFileInfo>;
+    /** Sandbox path of the home directory of the user operations run as. */
+    homeDirectory(): Promise<string>;
+}
+export interface SandboxCommands {
+    runCommand(cmd: string[], options?: RunCommandOptions): Promise<RunCommandResult>;
+}
+/** Reaching into the sandbox from the caller's side. */
+export interface SandboxNetwork {
+    /** HTTP request made from inside the sandbox. */
+    fetch(url: string, init?: SandboxFetchInit): Promise<Response>;
+    /** Opens a stream connection to the unix socket at `path` (e.g. an agent worker's). */
+    connect(path: string): Promise<SandboxConnection>;
+}
+/**
+ * Makes something listening in the sandbox reachable from the SDK's client over the network, without
+ * going through the backend's own connection. Declared when the sandbox is created (with the host
+ * clients reach it at), by the backends that can. Always authenticated: a scheme the sandbox's auth
+ * can't enforce is refused with SandboxEndpointError. An endpoint lasts until it is closed, past the
+ * sandbox object that exposed it.
+ */
+export interface SandboxAccessibleEndpoint {
+    /**
+     * How clients reach the machine, as the sandbox was created with ("host" or "host:port"). Several
+     * sandboxes may drive the same machine, each reached its own way: their endpoints are their own.
+     */
+    readonly accessibleHost: string;
+    exposeEndpoint(request: SandboxEndpointRequest): Promise<SandboxEndpoint>;
+    /** Stops accepting connections and revokes its credentials. No-op if already closed. */
+    closeEndpoint(endpointId: string): Promise<void>;
+    /**
+     * Makes sure it is served, starting its proxy again if that stopped (a reboot), with the same URL
+     * and credentials; false if it was closed, or its port has since been taken (expose another).
+     */
+    ensureEndpoint(endpointId: string): Promise<boolean>;
+}
+/** A sandbox that stops itself on a timer (Boat). */
+export interface SandboxExpiration {
+    /** When it stops itself; null if it never does. */
+    getExpiration(): Promise<Date | null>;
+    /** Makes it stop itself `seconds` from now; null: never. Returns when it now will. */
+    setExpiration(seconds: number | null): Promise<Date | null>;
+}
+/** Whether the sandbox has the SandboxExpiration capability. */
+export declare function hasExpiration<T extends object>(sandbox: T): sandbox is T & SandboxExpiration;
+/** What every backend provides. */
+export type Sandbox = SandboxFileOperations & SandboxCommands & SandboxNetwork & {
+    /** Releases what the sandbox holds open (a remote connection). Optional: most hold nothing. */
+    close?(): void;
+};
+export declare class SandboxPathError extends Error {
+    name: string;
+}
+export declare class SandboxNotFoundError extends Error {
+    name: string;
+}
+/** The endpoint can't be exposed as asked (a scheme or port its auth doesn't allow, ...). */
+export declare class SandboxEndpointError extends Error {
+    name: string;
+}

package/dist/sandbox/api.js

@@ -0,0 +1,14 @@
+/** Whether the sandbox has the SandboxExpiration capability. */
+export function hasExpiration(sandbox) {
+    return "getExpiration" in sandbox && "setExpiration" in sandbox;
+}
+export class SandboxPathError extends Error {
+    name = "SandboxPathError";
+}
+export class SandboxNotFoundError extends Error {
+    name = "SandboxNotFoundError";
+}
+/** The endpoint can't be exposed as asked (a scheme or port its auth doesn't allow, ...). */
+export class SandboxEndpointError extends Error {
+    name = "SandboxEndpointError";
+}

package/dist/sandbox/boatService.d.ts

@@ -0,0 +1,52 @@
+import { BoatApi, type Sandbox as BoatMachine } from "@boatdev/sdk";
+import { type Sandbox, type SandboxAccessibleEndpoint, type SandboxExpiration } from "./api.ts";
+import { type SandboxEndpointAuth } from "./endpointProxy.ts";
+export declare const BOAT_API_URL = "https://boat.dev/api/v1";
+export declare function createBoatApi(apiKey: string, basePath?: string): BoatApi;
+/** A call to Boat that failed: its HTTP status and Boat's error code. */
+export declare class BoatError extends Error {
+    readonly status: number;
+    readonly code: string;
+    name: string;
+    constructor(status: number, code: string, message: string);
+}
+export type BoatSandboxOptions = {
+    /** Where the sandbox's endpoint proxy listens; Boat publishes it. Defaults to 8900. */
+    proxyPort?: number;
+    /** Sandbox path the endpoint proxy keeps its records in; defaults to ~/.local/state/hyperbrane/endpoints. */
+    stateDirectory?: string;
+};
+/**
+ * A Boat sandbox (https://boat.dev), driven through Boat's API alone (its SDK): files through its
+ * file calls, commands through its command call (one shell line, up to 600s), and what needs a
+ * stream into the sandbox through the sandbox's own endpoints: `connect` is an "sse" endpoint to
+ * the socket, `fetch` an "http" one (so docker's responses stream). Those endpoints, like any the
+ * sandbox exposes, sit behind one proxy that Boat publishes on a URL of its own (boatHostPortAuth).
+ * Sandbox paths are paths in the sandbox; the sandbox must be running (ensureBoatRunning).
+ */
+export declare function createBoatSandbox(api: BoatApi, sandboxId: string, { proxyPort, stateDirectory }?: BoatSandboxOptions): Sandbox & SandboxAccessibleEndpoint & SandboxExpiration;
+/**
+ * Endpoints published by Boat: the proxy listens on the accessible host's port inside the sandbox
+ * and checks the bearer or basic credentials it mints per endpoint (proxyCredentialsAuth), and
+ * Boat's hostPort makes that port public, with Boat's TLS, on a URL of its own:
+ * https://<sandbox>-<port>.on.boat.dev. Boat's own guard for a port (a token it trades for a
+ * cookie) isn't used: a client can't carry it through a POST, nor a browser keep it across sites.
+ */
+export declare function boatHostPortAuth(api: BoatApi, sandboxId: string): SandboxEndpointAuth;
+/** Creates a sandbox, names it, and waits until it runs commands. */
+export declare function createBoatMachine(api: BoatApi, { name }: {
+    name: string;
+}): Promise<BoatMachine>;
+/** The sandbox, running: one that was stopped (archived) is resumed, its disk as it was, first. */
+export declare function ensureBoatRunning(api: BoatApi, sandboxId: string): Promise<BoatMachine>;
+/** Stops the sandbox, saving its disk first (Boat archives it), for a later ensureBoatRunning. */
+export declare function archiveBoatMachine(api: BoatApi, sandboxId: string): Promise<void>;
+/**
+ * Lets `publicKey` (OpenSSH) log in to the running sandbox, and says where: Boat's SSH endpoint for
+ * it and its user. The endpoint may change when the sandbox is resumed on another machine.
+ */
+export declare function authorizeBoatSshKey(api: BoatApi, sandboxId: string, publicKey: string): Promise<{
+    host: string;
+    port: number;
+    user: string;
+}>;