@brass-build/cli 0.1.0

package/dist/session.js

@@ -0,0 +1,224 @@
+// Browser sign-in for the CLI, and the session-backed auth provider it
+// produces. `brass login` runs the RFC 8628 device-authorization grant: the
+// CLI mints a grant, opens the browser to the approval page with the user
+// code prefilled (and prints the URL + code as a fallback for a headless
+// box), then polls until the human approves. Approval mints the same tokens
+// `/refresh` returns, including the opaque `session_token` the CLI stores to
+// keep refreshing. The CLI's OAuth client is the seeded
+// `brass_app_internal_cli`; its redirect allowlist is the loopback wildcards,
+// which the `/refresh` Origin gate checks the CLI's portless 127.0.0.1 origin
+// against on every later token refresh.
+import { spawn } from 'node:child_process';
+import { BrassApiError } from './api.js';
+// The seeded CLI OAuth client (see infra/lib/api-stack.ts). Stable across
+// environments, so one CLI build signs in against prod or dev.
+export const CLI_APP_ID = 'brass_app_internal_cli';
+// The Origin the CLI presents on every `/refresh` call (a command refreshing
+// its access token from the stored session). The CLI app's loopback wildcard
+// allowlist matches any 127.0.0.1 origin, port ignored, so this portless
+// loopback origin passes the `/refresh` Origin gate.
+const REFRESH_ORIGIN = 'http://127.0.0.1';
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Refresh an access token at `/refresh` from the stored session pointer
+// (`sid`). A form-encoded body keeps this a CORS simple request (the auth API
+// serves no preflight); the Origin header is required by the endpoint's
+// allowlist and satisfied by a loopback origin.
+export async function postRefresh(authBaseUrl, sid, origin = REFRESH_ORIGIN, now = Date.now()) {
+    const body = new URLSearchParams({ sid });
+    const url = `${authBaseUrl}/refresh?${new URLSearchParams({ app_id: CLI_APP_ID }).toString()}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded', origin },
+            body,
+        });
+    }
+    catch (cause) {
+        throw new BrassApiError(0, `Network error reaching ${authBaseUrl}: ${String(cause)}`);
+    }
+    if (!response.ok) {
+        // Carry the status, and name what a 401 means. Every command reaches the
+        // data API through this refresh, so this error is what the caller
+        // classifies the whole attempt by, and a status-free error here is
+        // indistinguishable from a request that never completed: that is what
+        // turns an expired session into a report of an unreachable API.
+        throw new BrassApiError(response.status, response.status === 401
+            ? `Your Brass sign-in is no longer valid (401). Run 'brass login' to sign in again.`
+            : `Sign-in exchange failed (${response.status}).`);
+    }
+    const json = (await response.json());
+    return {
+        accessToken: json.access_token,
+        idToken: json.id_token,
+        // Default the lifetime when the server omits it: `undefined * 1000` is
+        // `NaN`, which makes `expiresAt` NaN and the `Date.now() >= expiresAt`
+        // refresh guard permanently false, so the in-process token would never
+        // re-refresh. `pollDeviceToken` already guards the same field.
+        expiresAt: now + (json.expires_in ?? 3600) * 1000,
+        ...(json.session_token ? { sessionToken: json.session_token } : {}),
+    };
+}
+// Decode the email claim from a Cognito id token, best-effort (used only for
+// the "Signed in as ..." confirmation; never for authorization).
+export function decodeEmail(idToken) {
+    const part = idToken.split('.')[1];
+    if (part === undefined)
+        return undefined;
+    try {
+        const claims = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+        return typeof claims.email === 'string' ? claims.email : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function deviceAuthorize(authBaseUrl, now = Date.now()) {
+    const body = new URLSearchParams({ app_id: CLI_APP_ID });
+    let response;
+    try {
+        response = await fetch(`${authBaseUrl}/device/authorize`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body,
+        });
+    }
+    catch (cause) {
+        throw new Error(`Network error reaching ${authBaseUrl}: ${String(cause)}`);
+    }
+    if (!response.ok)
+        throw new Error(`Device sign-in could not start (${response.status})`);
+    const json = (await response.json());
+    return {
+        deviceCode: json.device_code,
+        userCode: json.user_code,
+        verificationUri: json.verification_uri,
+        ...(json.verification_uri_complete
+            ? { verificationUriComplete: json.verification_uri_complete }
+            : {}),
+        // Guard both fields the poll loop depends on. The server always sends
+        // them, but a missing `interval` makes `sleep(NaN * 1000)` a zero-delay
+        // tight poll of /device/token, and a missing `expires_in` makes the
+        // `now() >= expiresAt` deadline check always false, so the loop never
+        // times out. The token-exchange path already guards `expires_in` the same
+        // way. RFC 8628 defaults: 5s poll interval, 600s grant lifetime.
+        intervalSeconds: json.interval ?? 5,
+        expiresAt: now + (json.expires_in ?? 600) * 1000,
+    };
+}
+export async function pollDeviceTokenOnce(authBaseUrl, deviceCode, now = Date.now()) {
+    const body = new URLSearchParams({ device_code: deviceCode, app_id: CLI_APP_ID });
+    let response;
+    try {
+        response = await fetch(`${authBaseUrl}/device/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body,
+        });
+    }
+    catch {
+        // A transient network error mid-poll: the device grant is still valid
+        // server-side, so report "still pending" and let the caller poll again
+        // rather than aborting a sign-in a retry would complete.
+        // (`deviceAuthorize` / `postRefresh` guard their fetches the same way.)
+        return { state: 'pending' };
+    }
+    const json = (await response.json().catch(() => ({})));
+    if (response.ok && json.access_token && json.id_token) {
+        return {
+            state: 'approved',
+            tokens: {
+                accessToken: json.access_token,
+                idToken: json.id_token,
+                expiresAt: now + (json.expires_in ?? 3600) * 1000,
+                ...(json.session_token ? { sessionToken: json.session_token } : {}),
+            },
+        };
+    }
+    // The user declined: the one terminal refusal.
+    if (json.error === 'access_denied')
+        return { state: 'denied' };
+    // RFC 8628 §3.5: polling too fast. The caller backs off.
+    if (json.error === 'slow_down')
+        return { state: 'slow_down' };
+    // Everything else — `authorization_pending`, a transient non-2xx (5xx/429),
+    // a non-JSON body, or an error code this pinned CLI does not recognize — is
+    // "keep waiting". The caller's deadline check is the single terminal bound,
+    // so an unknown error or a server blip does not abort a sign-in the user is
+    // one poll away from completing; a genuinely expired grant simply ends
+    // there as a clean timeout.
+    return { state: 'pending' };
+}
+// Poll `/device/token` until the grant is approved, or reject on denial /
+// expiry. Honors the server-supplied interval; treats `authorization_pending`
+// as "keep waiting".
+export async function pollDeviceToken(authBaseUrl, auth, opts = {}) {
+    const sleep = opts.sleep ?? realSleep;
+    const now = opts.now ?? (() => Date.now());
+    // Server-supplied poll interval, bumped on `slow_down` per RFC 8628 §3.5.
+    let intervalSeconds = auth.intervalSeconds;
+    for (;;) {
+        await sleep(intervalSeconds * 1000);
+        if (now() >= auth.expiresAt)
+            throw new Error('Device sign-in timed out. Run `brass login` again.');
+        const outcome = await pollDeviceTokenOnce(authBaseUrl, auth.deviceCode, now());
+        if (outcome.state === 'approved')
+            return outcome.tokens;
+        if (outcome.state === 'denied')
+            throw new Error('Sign-in was denied.');
+        if (outcome.state === 'slow_down')
+            intervalSeconds += 5;
+    }
+}
+export async function loginDevice(options) {
+    const auth = await deviceAuthorize(options.authBaseUrl);
+    (options.onPrompt ?? defaultDevicePrompt)(auth);
+    (options.openBrowser ?? openBrowser)(auth.verificationUriComplete ?? auth.verificationUri);
+    const tokens = await pollDeviceToken(options.authBaseUrl, auth, options.sleep ? { sleep: options.sleep } : {});
+    if (!tokens.sessionToken)
+        throw new Error('Device sign-in did not return a session token.');
+    return { sessionToken: tokens.sessionToken, email: decodeEmail(tokens.idToken) };
+}
+function defaultDevicePrompt(auth) {
+    const target = auth.verificationUriComplete ?? auth.verificationUri;
+    process.stderr.write('\nOpening your browser to approve this sign-in.\n' +
+        `If it doesn't open, go to:\n  ${target}\n` +
+        `and confirm the code:  ${auth.userCode}\n` +
+        '\nWaiting for approval...\n');
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    const [cmd, args] = platform === 'darwin'
+        ? ['open', [url]]
+        : platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        // A missing opener (`xdg-open` absent on a headless box) surfaces ENOENT
+        // as an ASYNC 'error' event, not a throw; an unhandled one crashes the
+        // process. Swallow it: the URL is already printed, so the user opens it
+        // themselves.
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // The URL was already printed; a failed auto-open is not fatal.
+    }
+}
+// An auth provider backed by a stored login session: refresh the access
+// token on first use and whenever it is within the skew window of expiry,
+// caching it in memory for the process's lifetime.
+export function sessionAuth(authBaseUrl, sid) {
+    let cached = null;
+    const SKEW_MS = 60 * 1000;
+    return {
+        async headers() {
+            if (cached === null || Date.now() >= cached.expiresAt - SKEW_MS) {
+                cached = await postRefresh(authBaseUrl, sid);
+            }
+            return { authorization: `Bearer ${cached.accessToken}`, 'x-id-token': cached.idToken };
+        },
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,17 @@
+import type { CredentialsFile, Profile, StoredCredential } from './config.js';
+export declare function credentialsFilePath(env?: NodeJS.ProcessEnv): string;
+export declare function readCredentialsFile(env?: NodeJS.ProcessEnv): Promise<CredentialsFile | null>;
+export declare function writeStoredCredential(target: Profile, credential: StoredCredential | null, env?: NodeJS.ProcessEnv): Promise<void>;
+export interface PendingLogin {
+    authBaseUrl: string;
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    intervalSeconds: number;
+    expiresAt: number;
+}
+export declare function pendingLoginFilePath(env?: NodeJS.ProcessEnv): string;
+export declare function readPendingLogin(profile: Profile, env?: NodeJS.ProcessEnv): Promise<PendingLogin | null>;
+export declare function writePendingLogin(profile: Profile, pending: PendingLogin | null, env?: NodeJS.ProcessEnv): Promise<void>;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAM9E,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAIhF;AAED,wBAAsB,mBAAmB,CACvC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CASjC;AAKD,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,gBAAgB,GAAG,IAAI,EACnC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,IAAI,CAAC,CAMf;AAKD,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAEjF;AAaD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAY9B;AAKD,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,YAAY,GAAG,IAAI,EAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/store.js

@@ -0,0 +1,90 @@
+import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+// Where `brass login` persists its credential, and where
+// `publish` / `schema` / `whoami` look for it when no `--token` /
+// `BRASS_SERVICE_TOKEN` was given. Honors `XDG_CONFIG_HOME`, else
+// `~/.config/brass/credentials.json`.
+export function credentialsFilePath(env = process.env) {
+    const base = env['XDG_CONFIG_HOME'];
+    const root = base && base.trim() !== '' ? base : join(homedir(), '.config');
+    return join(root, 'brass', 'credentials.json');
+}
+export async function readCredentialsFile(env = process.env) {
+    try {
+        const raw = await readFile(credentialsFilePath(env), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || typeof parsed.credentials !== 'object')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+// Merge one profile's stored credential into the file (0600 so the session
+// pointer is not world-readable), or clear it when `credential` is null.
+// Preserves the other env's entry.
+export async function writeStoredCredential(target, credential, env = process.env) {
+    const existing = (await readCredentialsFile(env)) ?? { version: 1, credentials: {} };
+    const credentials = { ...existing.credentials };
+    if (credential === null)
+        delete credentials[target];
+    else
+        credentials[target] = credential;
+    await writeOwnerOnlyJson(credentialsFilePath(env), { version: 1, credentials });
+}
+// Sibling of the credentials file: the in-flight sign-in per profile. Kept
+// out of credentials.json so starting a new sign-in never disturbs a stored
+// session until the new grant is approved.
+export function pendingLoginFilePath(env = process.env) {
+    return join(dirname(credentialsFilePath(env)), 'pending-login.json');
+}
+async function readPendingLoginsFile(env) {
+    try {
+        const raw = await readFile(pendingLoginFilePath(env), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || typeof parsed.pending !== 'object')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readPendingLogin(profile, env = process.env) {
+    const file = await readPendingLoginsFile(env);
+    const entry = file?.pending[profile];
+    if (entry === undefined ||
+        typeof entry.authBaseUrl !== 'string' ||
+        typeof entry.deviceCode !== 'string' ||
+        typeof entry.expiresAt !== 'number') {
+        return null;
+    }
+    return entry;
+}
+// Merge one profile's pending grant into the file (0600: the device code is
+// redeemable for tokens once the human approves), or clear it when `pending`
+// is null. Preserves the other profiles' entries.
+export async function writePendingLogin(profile, pending, env = process.env) {
+    const existing = (await readPendingLoginsFile(env)) ?? { version: 1, pending: {} };
+    const entries = { ...existing.pending };
+    if (pending === null)
+        delete entries[profile];
+    else
+        entries[profile] = pending;
+    await writeOwnerOnlyJson(pendingLoginFilePath(env), {
+        version: 1,
+        pending: entries,
+    });
+}
+async function writeOwnerOnlyJson(path, payload) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    // writeFile's `mode` applies only when it CREATES the file; an existing
+    // file (an older CLI wrote it, or a permissive umask) keeps its old perms.
+    // chmod unconditionally so a rewrite tightens a file that is already too
+    // open, rather than leaving the secret group/world-readable.
+    await chmod(path, 0o600);
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const VERSION = "0.1.0";
+export declare const CLI_CLIENT_ID = "cli/0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,eAAO,MAAM,aAAa,cAAmB,CAAC"}

package/dist/version.js

@@ -0,0 +1,8 @@
+// The package version the CLI reports on every data-API call (the
+// `x-brass-client` header; a Node process has no CORS so a header is
+// free here, unlike the SDK's query-param channel). Lets the platform
+// measure the CLI version distribution, in particular pinned CI copies.
+// A unit test pins this to package.json's version.
+export const VERSION = '0.1.0';
+export const CLI_CLIENT_ID = `cli/${VERSION}`;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,qEAAqE;AACrE,sEAAsE;AACtE,wEAAwE;AACxE,mDAAmD;AACnD,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,OAAO,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@brass-build/cli",
+  "version": "0.1.0",
+  "description": "Brass command-line tool: publish apps and pull schemas from a terminal or CI",
+  "type": "module",
+  "bin": {
+    "brass": "./dist/bin/brass.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__/**",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "type-check": "tsc -b",
+    "prepublishOnly": "tsc -b --force"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "typescript": "~6.0.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brass-build/cli.git"
+  },
+  "homepage": "https://brass.build",
+  "license": "MIT"
+}

package/src/api.ts

@@ -0,0 +1,195 @@
+// The HTTP client the commands share: a bearer-authenticated wrapper over
+// the Brass data API, plus the narrow wire types the CLI reads. Wire shapes
+// are declared here (not imported from `@brass-build/client`) so the CLI
+// stays a standalone package with no browser-SDK dependency; the shapes it
+// depends on are small and stable (the `/apps` + hosting surface).
+
+import type { AuthProvider } from './auth.js';
+import { CLI_CLIENT_ID } from './version.js';
+
+// A schema manifest as it rides on the wire (a document's resolved schema
+// and an app's `schema` declaration): the artifact's family word plus each
+// stream's JSON Schema. The CLI never interprets it, only transports it
+// verbatim.
+export interface BrassSchemaManifest {
+  family: string;
+  streams: Record<string, Record<string, unknown>>;
+}
+
+export type AppVisibility = 'private' | 'invitee_visible' | 'public';
+
+export interface AppDetail {
+  app_id: string;
+  name: string;
+  owner_organization_id?: string;
+  visibility?: AppVisibility;
+}
+
+export interface HostingStatus {
+  enabled: boolean;
+  slug: string | null;
+  url: string | null;
+  deployed: boolean;
+  active_version: string | null;
+  // Whether the edge gates the bundle behind the app's audience. A public
+  // showcase turns this off so the bundle is world-loadable.
+  require_access?: boolean;
+}
+
+export interface HostingUploadUrl {
+  upload_url: string;
+  version_id: string;
+  expires_in: number;
+}
+
+export type HostingVersionStatus = 'pending' | 'ready' | 'failed';
+
+export interface HostingVersion {
+  version_id: string;
+  status: HostingVersionStatus;
+  failure_reason?: string;
+  active: boolean;
+  // The deterministic content hash the publishing client recorded for this
+  // version's bundle (absent on versions uploaded before hashing was added).
+  // `publish` compares it against the local bundle to skip an unchanged
+  // re-upload.
+  content_hash?: string;
+}
+
+// What a document holds: its streams and the contract of each. A document
+// is a set of streams, not a representation, so this carries no family; the
+// document's TYPE is the `schema_type` on its detail response, which is what
+// `schema pull` assembles the app manifest's `family` from.
+export interface DocumentStreams {
+  // `schema` is absent on a stream the document holds whose contract does
+  // not resolve: nobody published one under that name, or this caller is
+  // outside the publisher's read audience.
+  streams: { name: string; schema?: Record<string, unknown> }[];
+  // Set when the document holds no records yet, so the streams are the ones
+  // the importing app says it will produce. Still the right thing to build
+  // against; the CLI transports it either way.
+  predicted?: true;
+}
+
+export interface DocumentTypeSummary {
+  schema_type?: string;
+}
+
+// An organization's agentic-coding instructions (its AGENTS.md / CLAUDE.md
+// body), from `GET /organizations/:id/agent-instructions`. `content` is empty
+// when the org has never set them.
+export interface AgentInstructionsResponse {
+  content: string;
+  updated_at?: string;
+  updated_by?: string;
+}
+
+// The narrow slice of `GET /organizations` the CLI reads: enough to resolve a
+// single-org caller's org id and to name the orgs when the caller must pick.
+export interface OrganizationSummary {
+  organization_id: string;
+  name: string;
+}
+
+export interface RefreshCapabilitiesResponse {
+  app_id: string;
+  manifest_origin: string;
+  opens: string[];
+  warnings?: string[];
+}
+
+// One error type for every API failure, carrying the HTTP status and the
+// server-authored message so the CLI can render it verbatim (the API returns
+// `{ error: string }` on the 4xx/5xx ladder).
+export class BrassApiError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'BrassApiError';
+    this.status = status;
+  }
+}
+
+export class BrassApi {
+  private readonly apiBaseUrl: string;
+  private readonly auth: AuthProvider;
+
+  constructor(apiBaseUrl: string, auth: AuthProvider) {
+    this.apiBaseUrl = apiBaseUrl;
+    this.auth = auth;
+  }
+
+  get<T>(path: string): Promise<T> {
+    return this.request<T>('GET', path);
+  }
+  post<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>('POST', path, body);
+  }
+  patch<T>(path: string, body?: unknown): Promise<T> {
+    return this.request<T>('PATCH', path, body);
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const headers: Record<string, string> = {
+      ...(await this.auth.headers()),
+      // Version telemetry; the api Lambda logs it so pinned CI copies
+      // stay visible in the deployed-version distribution.
+      'x-brass-client': CLI_CLIENT_ID,
+    };
+    let init: RequestInit = { method, headers };
+    if (body !== undefined) {
+      headers['content-type'] = 'application/json';
+      init = { ...init, body: JSON.stringify(body) };
+    }
+    let response: Response;
+    try {
+      response = await fetch(`${this.apiBaseUrl}${path}`, init);
+    } catch (cause) {
+      throw new BrassApiError(0, `Network error reaching ${this.apiBaseUrl}: ${String(cause)}`);
+    }
+    if (!response.ok) {
+      throw new BrassApiError(response.status, await errorMessage(response));
+    }
+    if (response.status === 204) return undefined as T;
+    return (await response.json()) as T;
+  }
+}
+
+// Upload bytes to a presigned S3 URL. Deliberately carries NO Brass headers
+// and no bearer: the presigned signature pins an exact header set, and a
+// stray `authorization` header would break it (the same rule the SDK's
+// `api-headers` module enforces on the document path).
+export async function putPresigned(
+  url: string,
+  bytes: Uint8Array,
+  contentType: string,
+): Promise<void> {
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: 'PUT',
+      headers: { 'content-type': contentType },
+      // fflate allocates a plain ArrayBuffer, so narrowing the generic off
+      // `ArrayBufferLike` is sound and satisfies fetch's `BufferSource`
+      // (which pins `ArrayBufferView<ArrayBuffer>`) across lib configs.
+      body: bytes as Uint8Array<ArrayBuffer>,
+    });
+  } catch (cause) {
+    throw new BrassApiError(0, `Network error uploading the bundle: ${String(cause)}`);
+  }
+  if (!response.ok) {
+    throw new BrassApiError(response.status, `Bundle upload failed (${response.status})`);
+  }
+}
+
+// Pull the server's `{ error }` message off a failed response, falling back
+// to the bare status when the body is not the expected shape.
+async function errorMessage(response: Response): Promise<string> {
+  try {
+    const body = (await response.json()) as { error?: unknown };
+    if (typeof body.error === 'string' && body.error !== '') return body.error;
+  } catch {
+    // Non-JSON body (an edge / gateway error); fall through to the status.
+  }
+  return `Request failed with status ${response.status}`;
+}