busabase-sdk 0.10.2 → 0.11.0

package/README.md

@@ -40,9 +40,49 @@ Every constructor field is optional and falls back to an environment variable:
 
 `baseUrl` accepts either the server root (`http://host`) or the full API path (`http://host/api/v1`) — the `/api/v1` suffix is normalized away.
 
-## Two entry points
+## Local AirApp OAuth
 
-**`Busabase` class** — an ergonomic wrapper with namespaced methods (`bb.bases`, `bb.records`, `bb.changeRequests`, `bb.nodes`, `bb.views`, `bb.assets`, `bb.skills`, `bb.docs`, `bb.folders`, `bb.comments`, `bb.auditEvents`, `bb.agent`, `bb.agentTasks`, `bb.embedLinks`, `bb.search()`, `bb.health()`, `bb.me()`). Drop to `bb.client` for the raw oRPC client (e.g. `bb.client.system.meta()`).
+Local Hono apps can connect without asking the user to run the CLI or paste an API key. Start a PKCE authorization request, validate the callback, exchange the code, then register the returned token set in the local Busabase credential directory:
+
+```ts
+import {
+  createBusabaseOAuthRequest,
+  exchangeBusabaseOAuthCode,
+  parseBusabaseOAuthCallback,
+} from "busabase-sdk/oauth";
+import { storeBusabaseAirAppOAuthCredential } from "busabase-sdk/oauth-node";
+
+const request = await createBusabaseOAuthRequest({
+  baseUrl: "https://busabase.com",
+  redirectUri: "http://127.0.0.1:3107/auth/callback",
+});
+
+// Keep request.codeVerifier and request.state in the Hono server, then redirect
+// the browser to request.authorizeUrl.
+const code = parseBusabaseOAuthCallback(callbackUrl, request);
+const tokenSet = await exchangeBusabaseOAuthCode(request, code);
+storeBusabaseAirAppOAuthCredential({
+  appId: "kelly-invest-stock",
+  baseUrl: request.baseUrl,
+  tokenSet,
+});
+```
+
+The Node-only helper writes `~/.busabase/airapps/<app-id>.json` with an owner-only directory and file (`0700`/`0600`). Use `getBusabaseAirAppAccessToken()` inside Hono when proxying `/api/v1`; it refreshes and persists the token set when needed. Use `revokeBusabaseAirAppOAuthCredential()` on logout. The browser must never receive the `bso_` access token, `bsr_` refresh token, or PKCE verifier through JavaScript-visible storage. This local AirApp registration is separate from the CLI's active `~/.busabase/.env` profile.
+
+## Data client entry points
+
+**`Busabase` class** — an ergonomic wrapper with namespaced methods (`bb.bases`, `bb.records`, `bb.changeRequests`, `bb.nodes`, `bb.views`, `bb.assets`, `bb.fileTrees`, `bb.files`, `bb.docs`, `bb.comments`, `bb.auditEvents`, `bb.agent`, `bb.agentTasks`, `bb.embedLinks`, `bb.search()`, `bb.grep()`, `bb.health()`, `bb.me()`). Drop to `bb.client` for the raw oRPC client (e.g. `bb.client.system.meta()`).
+
+Reading or listing nodes goes through `bb.nodes`, whatever the node's type:
+
+```ts
+const docs = await bb.nodes.list({ types: ["doc"] }); // flat summaries, one call
+const detail = await bb.nodes.get({ nodeId }); // discriminated by `detail.type`
+if (detail.type === "doc") console.log(detail.body);
+```
+
+`bb.nodes.get` replaced the per-type gets (`docs.get` / `files.get` / `folders.get` / `fileTrees.get`), so a caller holding an id no longer has to discover the node's type before it can read it — and there is no `bb.folders` namespace any more (a folder is `type: "folder"`). `bb.docs` / `bb.files` / `bb.fileTrees` remain for the operations that are genuinely type-specific: creating a node, reading a Doc line range, updating a Doc body, and listing/reading a Skill-, Drive-, or AirApp file.
 
 **`createBusabaseClient(config?)`** — returns the raw, fully-typed [oRPC](https://orpc.unnoq.com) client directly, if you'd rather not wrap it in a class:
 

package/dist/chunk-5NYQX65A.js

@@ -0,0 +1,6 @@
+// src/url.ts
+function normalizeBaseUrl(raw) {
+  return raw.replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+}
+
+export { normalizeBaseUrl };

package/dist/chunk-J2DZKX7A.js

@@ -0,0 +1,175 @@
+import { normalizeBaseUrl } from './chunk-5NYQX65A.js';
+
+// ../../packages/busabase-contract/src/auth/device-authorization.ts
+var BUSABASE_AIRAPP_CLIENT_ID = "busabase-airapp";
+
+// src/oauth.ts
+var BusabaseOAuthError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.name = "BusabaseOAuthError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var oauthBaseUrl = (raw) => {
+  let url;
+  try {
+    url = new URL(normalizeBaseUrl(raw));
+  } catch {
+    throw new BusabaseOAuthError("invalid_base_url", "Busabase base URL is invalid");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:" || url.username || url.password || url.search || url.hash || url.pathname !== "/" && url.pathname !== "") {
+    throw new BusabaseOAuthError(
+      "invalid_base_url",
+      "Busabase base URL must be an HTTP(S) origin without credentials, query, or path"
+    );
+  }
+  return url.origin;
+};
+var randomBase64Url = (byteLength) => {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(byteLength));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+var digestBase64Url = async (value) => {
+  const encoded = new TextEncoder().encode(value);
+  const data = encoded.buffer.slice(
+    encoded.byteOffset,
+    encoded.byteOffset + encoded.byteLength
+  );
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", data);
+  let binary = "";
+  for (const byte of new Uint8Array(digest)) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+async function createBusabaseOAuthRequest(input) {
+  const baseUrl = oauthBaseUrl(input.baseUrl);
+  const redirectUri = new URL(input.redirectUri).toString();
+  const clientId = input.clientId ?? BUSABASE_AIRAPP_CLIENT_ID;
+  const codeVerifier = randomBase64Url(32);
+  const state = input.state ?? randomBase64Url(24);
+  const resource = new URL("/api/v1", baseUrl).toString();
+  const authorizeUrl = new URL("/api/oauth/authorize", baseUrl);
+  authorizeUrl.search = new URLSearchParams({
+    response_type: "code",
+    client_id: clientId,
+    resource,
+    scope: "api",
+    code_challenge: await digestBase64Url(codeVerifier),
+    code_challenge_method: "S256",
+    redirect_uri: redirectUri,
+    state
+  }).toString();
+  if (input.prompt) authorizeUrl.searchParams.set("prompt", input.prompt);
+  return {
+    authorizeUrl: authorizeUrl.toString(),
+    baseUrl,
+    clientId,
+    codeVerifier,
+    redirectUri,
+    resource,
+    state
+  };
+}
+function parseBusabaseOAuthCallback(callbackUrl, request) {
+  const callback = new URL(callbackUrl);
+  const error = callback.searchParams.get("error");
+  if (error) {
+    throw new BusabaseOAuthError(
+      error,
+      callback.searchParams.get("error_description") || "Busabase authorization was denied"
+    );
+  }
+  if (callback.searchParams.get("state") !== request.state) {
+    throw new BusabaseOAuthError("state_mismatch", "OAuth callback state did not match");
+  }
+  const issuer = callback.searchParams.get("iss");
+  let issuerMatches = false;
+  try {
+    issuerMatches = Boolean(issuer && new URL(issuer).origin === new URL(request.baseUrl).origin);
+  } catch {
+    issuerMatches = false;
+  }
+  if (!issuerMatches) {
+    throw new BusabaseOAuthError("issuer_mismatch", "OAuth callback issuer did not match");
+  }
+  const code = callback.searchParams.get("code");
+  if (!code) throw new BusabaseOAuthError("missing_code", "OAuth callback had no code");
+  return code;
+}
+var parseTokenResponse = async (response) => {
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    const code = typeof body?.error === "string" ? body.error : "token_request_failed";
+    const message = typeof body?.error_description === "string" ? body.error_description : `Busabase OAuth token request failed (${response.status})`;
+    throw new BusabaseOAuthError(code, message, response.status);
+  }
+  if (typeof body?.access_token !== "string" || typeof body.expires_in !== "number") {
+    throw new BusabaseOAuthError(
+      "invalid_token_response",
+      "Busabase returned an invalid token set"
+    );
+  }
+  return {
+    accessToken: body.access_token,
+    refreshToken: typeof body.refresh_token === "string" ? body.refresh_token : void 0,
+    expiresIn: body.expires_in,
+    expiresAt: new Date(Date.now() + body.expires_in * 1e3).toISOString(),
+    scope: typeof body.scope === "string" ? body.scope.split(/\s+/).filter(Boolean) : [],
+    tokenType: typeof body.token_type === "string" ? body.token_type : "Bearer",
+    user: body.user && typeof body.user === "object" ? body.user : void 0
+  };
+};
+async function exchangeBusabaseOAuthCode(request, code, fetchImpl = fetch) {
+  const response = await fetchImpl(new URL("/api/oauth/token", request.baseUrl), {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: request.clientId,
+      code,
+      code_verifier: request.codeVerifier,
+      redirect_uri: request.redirectUri,
+      resource: request.resource
+    })
+  });
+  return parseTokenResponse(response);
+}
+async function refreshBusabaseOAuthToken(input, fetchImpl = fetch) {
+  const baseUrl = oauthBaseUrl(input.baseUrl);
+  const response = await fetchImpl(new URL("/api/oauth/token", baseUrl), {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: input.refreshToken,
+      client_id: input.clientId ?? BUSABASE_AIRAPP_CLIENT_ID,
+      resource: new URL("/api/v1", baseUrl).toString()
+    })
+  });
+  return parseTokenResponse(response);
+}
+async function revokeBusabaseOAuthToken(input, fetchImpl = fetch) {
+  const baseUrl = oauthBaseUrl(input.baseUrl);
+  const response = await fetchImpl(new URL("/api/oauth/revoke", baseUrl), {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      token: input.token,
+      client_id: input.clientId ?? BUSABASE_AIRAPP_CLIENT_ID
+    })
+  });
+  if (!response.ok) {
+    throw new BusabaseOAuthError(
+      "revoke_failed",
+      `Busabase OAuth revocation failed (${response.status})`,
+      response.status
+    );
+  }
+}
+
+export { BUSABASE_AIRAPP_CLIENT_ID, BusabaseOAuthError, createBusabaseOAuthRequest, exchangeBusabaseOAuthCode, parseBusabaseOAuthCallback, refreshBusabaseOAuthToken, revokeBusabaseOAuthToken };