@brass-build/client 0.1.0

package/src/api-fetch.ts

@@ -0,0 +1,127 @@
+// The shared HTTP request wrapper: resolve token → 401 if missing →
+// auth header → app-assertion → fetch → parse → throw `BrassError` on
+// non-2xx → return parsed. Read paths that need the raw status without
+// throwing stay hand-written but still throw `BrassError`.
+
+import { applyAppAssertionHeader, applyClientVersionHeader } from './api-headers.js';
+import { BrassError } from './errors.js';
+import { fetchWithRetry } from './fetch-retry.js';
+
+export interface ApiRequest {
+  // Defaults to `GET`.
+  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+  path: string;
+  // JSON-encoded when present; sets `content-type: application/json`.
+  body?: unknown;
+}
+
+interface ApiFetchOptions {
+  apiBaseUrl: string;
+  getAccessToken: () => Promise<string | null>;
+  getAppAssertion?: () => Promise<string | null>;
+}
+
+export type ApiFetch = <T>(req: ApiRequest) => Promise<T>;
+
+export function createApiFetch(opts: ApiFetchOptions): ApiFetch {
+  const baseUrl = opts.apiBaseUrl.replace(/\/$/, '');
+
+  return async function apiFetch<T>(req: ApiRequest): Promise<T> {
+    const token = await opts.getAccessToken();
+    if (!token) {
+      // Reject before fetch: a deterministic 401, no network round-trip.
+      throw new BrassError('Not signed in', { status: 401 });
+    }
+    const headers: Record<string, string> = { authorization: `Bearer ${token}` };
+    if (req.body !== undefined) headers['content-type'] = 'application/json';
+    applyClientVersionHeader(headers);
+    await applyAppAssertionHeader(headers, opts.getAppAssertion);
+
+    const method = req.method ?? 'GET';
+    const init: RequestInit = { method, headers };
+    if (req.body !== undefined) init.body = JSON.stringify(req.body);
+
+    const url = `${baseUrl}${req.path}`;
+    // A GET is idempotent, so ride out a cold-API transient 5xx / 429
+    // (e.g. a 503 while the API scales into a concurrent read burst)
+    // rather than surfacing it as a hard failure; a write is never
+    // replayed here.
+    const response =
+      method === 'GET'
+        ? await fetchWithRetry(() => fetch(url, init))
+        : await fetch(url, init);
+    if (response.status === 204) return undefined as T;
+
+    const text = await response.text();
+    let parsed: unknown = undefined;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        // Leave `parsed` undefined; a non-2xx falls back to the generic
+        // message, a 2xx surfaces as the caller's own malformed-body guard.
+      }
+    }
+    if (!response.ok) {
+      throw brassErrorFromBody(response.status, parsed);
+    }
+    return parsed as T;
+  };
+}
+
+function isErrorBody(body: unknown): body is { error: string } {
+  return (
+    typeof body === 'object' &&
+    body !== null &&
+    typeof (body as { error?: unknown }).error === 'string'
+  );
+}
+
+// Build the BrassError for a non-2xx response body. Every SDK fetch
+// (apiFetch and the hand-written document open / create paths) throws
+// through here so the server's machine-readable denials, in particular
+// `code: "app_not_installed"`, survive into the error the caller (and
+// the SDK's own install-consent offer) can branch on.
+export function brassErrorFromBody(status: number, parsed: unknown): BrassError {
+  const message = isErrorBody(parsed) ? parsed.error : 'Request failed';
+  if (isNotInstalledBody(parsed)) {
+    return new BrassError(message, {
+      status,
+      code: 'app_not_installed',
+      organizationId: parsed.organization_id,
+    });
+  }
+  if (isSchemaConflictBody(parsed)) {
+    const title = (parsed as Record<string, unknown>)['title'];
+    return new BrassError(message, {
+      status,
+      code: 'schema_conflict',
+      ...(typeof title === 'string' ? { title } : {}),
+    });
+  }
+  return new BrassError(message, { status });
+}
+
+// The platform refuses to join a document this app's declared schema cannot
+// read, so a bookmark or a reload does not silently open one. The message is
+// the server's own line, which the client's dialog renders verbatim rather
+// than composing a reason of its own out of a shape it would have to keep in
+// step with the platform's.
+function isSchemaConflictBody(value: unknown): value is { error: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { code?: unknown }).code === 'schema_conflict'
+  );
+}
+
+function isNotInstalledBody(
+  value: unknown,
+): value is { error: string; code: 'app_not_installed'; organization_id: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { code?: unknown }).code === 'app_not_installed' &&
+    typeof (value as { organization_id?: unknown }).organization_id === 'string'
+  );
+}

package/src/api-headers.ts

@@ -0,0 +1,28 @@
+import { SDK_CLIENT_ID } from './version.js';
+
+// Attaches the acting-app assertion as `X-Brass-App-Assertion` when one
+// is available; a no-op when the caller has none.
+//
+// MUST only be applied to requests to the Brass data API. Never attach
+// it to other origins, in particular the presigned snapshot/upload
+// URLs the document path fetches, which must carry no Brass headers (a
+// stray header would also break the presigned signature's allowed-header
+// set).
+export async function applyAppAssertionHeader(
+  headers: Record<string, string>,
+  getAppAssertion?: () => Promise<string | null>,
+): Promise<void> {
+  const assertion = await getAppAssertion?.();
+  if (assertion) headers['x-brass-app-assertion'] = assertion;
+}
+
+// Attaches the SDK's version as `x-brass-client` (`sdk/<version>`), the same
+// value reported on /refresh and the WS connect URL, so the server sees the
+// deployed SDK version at the data-API surface too. The minimum-version gate
+// reads it at document open to serve a too-old client an upgrade message
+// (rendered verbatim through `session.error`). Same boundary as the
+// app-assertion header: data API only, never a presigned URL. Unconditional, so the
+// version distribution covers read-only apps that never refresh.
+export function applyClientVersionHeader(headers: Record<string, string>): void {
+  headers['x-brass-client'] = SDK_CLIENT_ID;
+}

package/src/auth-flow.ts

@@ -0,0 +1,125 @@
+import { SDK_CLIENT_ID } from './version.js';
+import { fetchWithRetry, RETRY_READ, RETRY_WRITE_503 } from './fetch-retry.js';
+
+// Fallback token lifetime if a /refresh response omits `expires_in`. The
+// server always sends it (so this is forward-compat robustness), but without a
+// fallback `Date.now() + undefined * 1000` is NaN, and the client's freshness
+// check `expiresAt - leeway > Date.now()` is then always false, so every
+// getAccessToken() would fire a fresh /refresh round-trip. Mirrors the CLI's
+// same guard.
+const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+
+export interface TokenSet {
+  accessToken: string;
+  idToken: string;
+  expiresAt: number;
+  // The acting-app assertion minted at /refresh, forwarded to the data
+  // API as `X-Brass-App-Assertion`. Absent when the proxy has no signing
+  // secret configured.
+  appAssertion?: string;
+}
+
+interface RefreshResponse {
+  access_token: string;
+  id_token: string;
+  expires_in: number;
+  app_assertion?: string;
+  // Present only for a fallback-mode request (a `brass_code` exchange or
+  // a `sid` echo): the opaque platform-session pointer the SDK holds in
+  // memory to keep refreshing without the cross-site cookie.
+  session_token?: string;
+}
+
+// The credential the SDK presents to POST /refresh.
+//   - `cookie`: the default; the browser attaches the `brass_auth` cookie
+//      and nothing is sent in the body. Works wherever the third-party
+//      cookie is allowed.
+//   - `code`: a one-time `brass_code` from the sign-in redirect, exchanged
+//      for tokens + a `session_token`. The incognito / Safari ITP fallback,
+//      used only after a `cookie` refresh came back empty.
+//   - `sessionToken`: the opaque pointer from a prior `code` exchange,
+//      echoed on every refresh once the cookie channel is known unavailable.
+export type RefreshCredential =
+  | { kind: 'cookie' }
+  | { kind: 'code'; code: string }
+  | { kind: 'sessionToken'; sessionToken: string };
+
+export interface RefreshResult {
+  tokens: TokenSet;
+  // Set only for fallback-mode refreshes (`code` / `sessionToken`). The
+  // SDK stores this and presents it as the `sessionToken` credential on
+  // later refreshes.
+  sessionToken?: string;
+}
+
+export function buildSignInUrl(authBaseUrl: string, appId: string, returnTo: string): string {
+  const url = new URL(`${authBaseUrl}/sign-in`);
+  url.searchParams.set('app_id', appId);
+  url.searchParams.set('return_to', returnTo);
+  return url.toString();
+}
+
+export function buildSignedOutOfAppUrl(
+  authBaseUrl: string,
+  appId: string,
+  returnTo: string,
+): string {
+  const url = new URL(`${authBaseUrl}/signed-out-of-app`);
+  url.searchParams.set('app_id', appId);
+  url.searchParams.set('return_to', returnTo);
+  return url.toString();
+}
+
+export async function refreshTokens(
+  authBaseUrl: string,
+  appId: string,
+  credential: RefreshCredential = { kind: 'cookie' },
+): Promise<RefreshResult | null> {
+  // `client` rides a query param, not a header: /refresh is deliberately
+  // a CORS simple request (no preflight), and any custom header would
+  // trip one. The server folds it into the token_refresh audit so the
+  // deployed SDK version distribution is measurable.
+  const url = `${authBaseUrl}/refresh?${new URLSearchParams({
+    app_id: appId,
+    client: SDK_CLIENT_ID,
+  }).toString()}`;
+  const init: RequestInit = { method: 'POST', credentials: 'include' };
+  if (credential.kind !== 'cookie') {
+    // A URLSearchParams body sends `Content-Type:
+    // application/x-www-form-urlencoded`, which keeps this a CORS
+    // "simple request" with no preflight OPTIONS, which the auth API
+    // does not serve. A JSON content-type would trip preflight.
+    const body = new URLSearchParams();
+    if (credential.kind === 'code') body.set('brass_code', credential.code);
+    else body.set('sid', credential.sessionToken);
+    init.body = body;
+  }
+  // Retry a transient failure (a cold-start 5xx / 429, or a network blip)
+  // rather than collapsing it into the same `null` a definitive 401 returns:
+  // `null` signs the user out and clears the login hint, so without a retry one
+  // hourly-refresh blip tears down a live session that was fine server-side. A
+  // definitive 401/403 is not in either replay set, so it still returns fast.
+  // The one-time `brass_code` exchange is single-use server-side, so its
+  // channel replays ONLY a pre-handler 503 (never a network throw, which might
+  // mean the code was already consumed); the cookie / sid channels are
+  // idempotent and replay the full transient set.
+  const policy = credential.kind === 'code' ? RETRY_WRITE_503 : RETRY_READ;
+  let response: Response;
+  try {
+    response = await fetchWithRetry(() => fetch(url, init), { policy });
+  } catch {
+    return null;
+  }
+  if (!response.ok) return null;
+  const json = (await response.json()) as RefreshResponse;
+  const result: RefreshResult = {
+    tokens: {
+      accessToken: json.access_token,
+      idToken: json.id_token,
+      expiresAt: Date.now() + (json.expires_in ?? DEFAULT_TOKEN_TTL_SECONDS) * 1000,
+      ...(json.app_assertion ? { appAssertion: json.app_assertion } : {}),
+    },
+  };
+  if (json.session_token) result.sessionToken = json.session_token;
+  return result;
+}