@superblocksteam/sdk 2.0.151 → 2.0.152-next.0

package/src/client.ts

@@ -2824,6 +2824,25 @@ export interface DollarLedgerRow {
   usageType: "ai_credits" | "deployed_app";
 }
 
+export interface UsageGroupRow {
+  actorId: string | null;
+  actorType: "ai_agent" | "user";
+  applicationId: string | null;
+  applicationName: string | null;
+  /** Checkpoint (accepted AI change) this usage rolled up to; null = no
+   * checkpoint. Absent entirely on servers that predate checkpoint mapping. */
+  checkpointId?: string | null;
+  /** Checkpoint commit message; null when the caller lacks application-update permission. */
+  checkpointLabel: string | null;
+  creditsUsed?: number;
+  date: string;
+  email: string | null;
+  name: string | null;
+  onDemandCreditsUsed?: number;
+  recordedAt: string | null;
+  unbilledCreditsUsed?: number;
+}
+
 export interface BillingUsageRecordsResponse {
   agentUsage?: AgentUsageRow[];
   applicationUsageRows?: ApplicationUsageRow[];
@@ -2832,6 +2851,8 @@ export interface BillingUsageRecordsResponse {
   enterpriseBillingWindows?: unknown[];
   rows: UsageRecordRow[];
   seatAssignments?: unknown[];
+  // undefined = server predates checkpoint rollups; [] = rollups supported, no usage in range.
+  usageGroupRows?: UsageGroupRow[];
 }
 
 export interface UserCreditLimit {

package/src/collect-sdk-apis.mts

@@ -1,7 +1,7 @@
 import path from "node:path";
 
 import {
-  extractIntegrationsFromSource,
+  extractApiIntegrations,
   type IntegrationInfo,
 } from "./extract-api-integrations.mjs";
 import { parseSdkRegistryWithExportNames } from "./parse-sdk-registry.mjs";
@@ -10,6 +10,20 @@ type SdkApiEntry = {
   entryPoint: string;
   exportName?: string;
   integrations?: IntegrationInfo[];
+  unresolvedIntegrations?: string[];
+};
+
+export type CollectSdkApisOptions = {
+  onUnresolvedIntegrations?: (
+    apiName: string,
+    entryPoint: string,
+    unresolvedKeys: string[],
+  ) => void;
+  onExtractionError?: (
+    apiName: string,
+    entryPoint: string,
+    error: unknown,
+  ) => void;
 };
 
 type SdkApisResult = Record<string, SdkApiEntry>;
@@ -17,8 +31,99 @@ type SdkApisResult = Record<string, SdkApiEntry>;
 type CollectSdkApisFs = {
   pathExists: (p: string) => Promise<boolean>;
   readFile: (p: string, encoding: "utf-8") => Promise<string>;
+  /**
+   * Used to canonicalize symlinks for app-root containment checks. An
+   * in-root path can lexically pass `resolveContainedPath` while being a
+   * symlink whose real target lives outside `root`; when `realpath` is
+   * provided, `resolveContainedRealPath` re-verifies containment against
+   * the canonicalized (symlink-resolved) path before it is read. When
+   * omitted, containment falls back to the lexical check only.
+   */
+  realpath?: (p: string) => Promise<string>;
 };
 
+/**
+ * Resolves `relativePath` against `root` and returns the resolved absolute
+ * path only if it stays contained within `root`; returns `undefined`
+ * otherwise (including for a path that resolves to exactly `root` plus a
+ * differently-cased or malformed suffix — only exact containment counts).
+ *
+ * Defense in depth against path traversal: the extractor
+ * (extract-api-integrations.ts) already filters `..`-prefixed candidates
+ * before ever proposing them, but that filtering is posix-only. `pathImpl`
+ * defaults to the real `node:path` (win32 semantics on Windows, posix
+ * elsewhere), so this re-verifies containment using whichever path
+ * semantics actually apply at runtime — a `relativePath` the extractor
+ * considered safe on POSIX could still escape `root` here on Windows, where
+ * backslashes are separators. Also protects against any future extractor
+ * change that stops filtering candidates. `pathImpl` is overridable so
+ * win32 containment semantics can be exercised directly in tests on a POSIX
+ * runner, independent of the host OS.
+ */
+export function resolveContainedPath(
+  root: string,
+  relativePath: string,
+  pathImpl: typeof path = path,
+): string | undefined {
+  const resolvedRoot = pathImpl.resolve(root);
+  const resolved = pathImpl.resolve(root, relativePath);
+  if (
+    resolved !== resolvedRoot &&
+    !resolved.startsWith(resolvedRoot + pathImpl.sep)
+  ) {
+    return undefined;
+  }
+  return resolved;
+}
+
+/**
+ * Like `resolveContainedPath`, but also canonicalizes symlinks before
+ * asserting containment, so an in-root path that is a symlink pointing
+ * outside `root` is rejected rather than silently followed.
+ *
+ * First runs the cheap lexical `resolveContainedPath` check; if that already
+ * fails, returns `undefined` without touching the filesystem. If
+ * `deps.realpath` is not provided, returns the lexical result unchanged —
+ * containment falls back to the lexical check only (documented fallback,
+ * e.g. for callers/tests that don't need symlink defense). If `realpath` is
+ * provided, both `root` and the lexically-resolved path are canonicalized
+ * and the same containment check is re-run against the canonical values;
+ * the canonical resolved path is returned only if it is still contained.
+ * If `realpath` throws (e.g. the path does not exist), returns `undefined`
+ * rather than throwing.
+ */
+export async function resolveContainedRealPath(
+  root: string,
+  relativePath: string,
+  deps: {
+    realpath?: (p: string) => Promise<string>;
+    pathImpl?: typeof path;
+  },
+): Promise<string | undefined> {
+  const pathImpl = deps.pathImpl ?? path;
+  const lexicallyResolved = resolveContainedPath(root, relativePath, pathImpl);
+  if (!lexicallyResolved) {
+    return undefined;
+  }
+  if (!deps.realpath) {
+    return lexicallyResolved;
+  }
+
+  try {
+    const canonicalRoot = await deps.realpath(pathImpl.resolve(root));
+    const canonicalResolved = await deps.realpath(lexicallyResolved);
+    if (
+      canonicalResolved !== canonicalRoot &&
+      !canonicalResolved.startsWith(canonicalRoot + pathImpl.sep)
+    ) {
+      return undefined;
+    }
+    return canonicalResolved;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Collect SDK API entry points and declared integrations from the app's registry
  * at server/apis/index.ts. Keys match Object.keys(registry.default) so
@@ -26,12 +131,17 @@ type CollectSdkApisFs = {
  *
  * @param root - App root directory
  * @param fs - File system operations (pathExists, readFile)
- * @returns Map of API name → { entryPoint, exportName?, integrations? } or
- * empty object if no registry exists
+ * @param options - Optional callbacks: onUnresolvedIntegrations for
+ * reporting integration keys that could not be resolved to a plugin/id, and
+ * onExtractionError for reporting when a registered API's source file could
+ * not be read or parsed (the entry point is still emitted bare in that case).
+ * @returns Map of API name → { entryPoint, exportName?, integrations?,
+ * unresolvedIntegrations? } or empty object if no registry exists
  */
 export async function collectSdkApisFromRegistry(
   root: string,
   fs: CollectSdkApisFs,
+  options?: CollectSdkApisOptions,
 ): Promise<SdkApisResult> {
   const sdkRegistryPath = path.join(root, "server/apis/index.ts");
   if (!(await fs.pathExists(sdkRegistryPath))) {
@@ -57,13 +167,39 @@ export async function collectSdkApisFromRegistry(
 
     try {
       const source = await fs.readFile(absolutePath, "utf-8");
-      const integrations = extractIntegrationsFromSource(source);
+      const { integrations, unresolvedKeys } = await extractApiIntegrations({
+        source,
+        entryPoint: registryEntry.entryPoint,
+        readSource: async (relativePath) => {
+          const resolved = await resolveContainedRealPath(root, relativePath, {
+            realpath: fs.realpath,
+          });
+          if (!resolved) {
+            return undefined;
+          }
+          // realpath (above) already requires the path to exist, so this is
+          // a harmless backstop rather than the primary existence check.
+          if (!(await fs.pathExists(resolved))) {
+            return undefined;
+          }
+          return fs.readFile(resolved, "utf-8");
+        },
+      });
       if (integrations.length > 0) {
         entry.integrations = integrations;
       }
-    } catch {
+      if (unresolvedKeys.length > 0) {
+        entry.unresolvedIntegrations = unresolvedKeys;
+        options?.onUnresolvedIntegrations?.(
+          apiName,
+          registryEntry.entryPoint,
+          unresolvedKeys,
+        );
+      }
+    } catch (error) {
       // Integration extraction is best-effort. If a source file cannot be read,
       // still emit the entry point so SDK execution continues to work.
+      options?.onExtractionError?.(apiName, registryEntry.entryPoint, error);
     }
 
     sdkApis[apiName] = entry;

package/src/collect-sdk-apis.test.mts

@@ -2,7 +2,138 @@ import path from "node:path";
 
 import { describe, it, expect, vi } from "vitest";
 
-import { collectSdkApisFromRegistry } from "./collect-sdk-apis.mjs";
+import {
+  collectSdkApisFromRegistry,
+  resolveContainedPath,
+  resolveContainedRealPath,
+} from "./collect-sdk-apis.mjs";
+
+describe("resolveContainedPath", () => {
+  it("returns undefined for a win32 relative path that traverses above root", () => {
+    // This genuinely exercises win32 path semantics (backslash separators)
+    // on a POSIX test runner by passing path.win32 explicitly, rather than
+    // relying on the host OS's real path module.
+    const result = resolveContainedPath(
+      "C:\\app",
+      "server\\apis\\..\\..\\..\\secret.ts",
+      path.win32,
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("returns the resolved absolute path for a win32 relative path that stays within root", () => {
+    const result = resolveContainedPath(
+      "C:\\app",
+      "server\\apis\\index.ts",
+      path.win32,
+    );
+
+    expect(result).toBe(
+      path.win32.resolve("C:\\app", "server\\apis\\index.ts"),
+    );
+  });
+
+  it("returns the resolved absolute path for a posix relative path that stays within root", () => {
+    const result = resolveContainedPath(
+      "/app",
+      "server/apis/index.ts",
+      path.posix,
+    );
+
+    expect(result).toBe(path.posix.resolve("/app", "server/apis/index.ts"));
+  });
+
+  it("returns undefined for a posix relative path that escapes root", () => {
+    const result = resolveContainedPath("/app", "../secret.ts", path.posix);
+
+    expect(result).toBeUndefined();
+  });
+});
+
+describe("resolveContainedRealPath", () => {
+  it("returns undefined when an in-root symlink canonicalizes outside root", async () => {
+    const realpathMap: Record<string, string> = {
+      "/app": "/app",
+      "/app/server/apis/evil.ts": "/etc/passwd",
+    };
+    const realpath = async (p: string) => {
+      const canonical = realpathMap[p];
+      if (canonical === undefined) {
+        throw new Error(`ENOENT: no such file, realpath '${p}'`);
+      }
+      return canonical;
+    };
+
+    const result = await resolveContainedRealPath(
+      "/app",
+      "server/apis/evil.ts",
+      { realpath, pathImpl: path.posix },
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("returns the canonical path when an in-root symlink stays within root", async () => {
+    const realpathMap: Record<string, string> = {
+      "/app": "/app",
+      "/app/server/apis/link.ts": "/app/server/apis/real.ts",
+    };
+    const realpath = async (p: string) => {
+      const canonical = realpathMap[p];
+      if (canonical === undefined) {
+        throw new Error(`ENOENT: no such file, realpath '${p}'`);
+      }
+      return canonical;
+    };
+
+    const result = await resolveContainedRealPath(
+      "/app",
+      "server/apis/link.ts",
+      { realpath, pathImpl: path.posix },
+    );
+
+    expect(result).toBe("/app/server/apis/real.ts");
+  });
+
+  it("falls back to the lexical result unchanged when no realpath is provided", async () => {
+    const result = await resolveContainedRealPath(
+      "/app",
+      "server/apis/index.ts",
+      { pathImpl: path.posix },
+    );
+
+    expect(result).toBe(
+      resolveContainedPath("/app", "server/apis/index.ts", path.posix),
+    );
+  });
+
+  it("returns undefined when realpath throws (e.g. missing file)", async () => {
+    const realpath = async () => {
+      throw new Error("ENOENT: no such file, realpath");
+    };
+
+    const result = await resolveContainedRealPath(
+      "/app",
+      "server/apis/missing.ts",
+      { realpath, pathImpl: path.posix },
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined when the lexical check itself fails (never calls realpath)", async () => {
+    const realpath = vi.fn();
+
+    const result = await resolveContainedRealPath("/app", "../secret.ts", {
+      realpath,
+      pathImpl: path.posix,
+    });
+
+    expect(result).toBeUndefined();
+    expect(realpath).not.toHaveBeenCalled();
+  });
+});
 
 describe("collectSdkApisFromRegistry", () => {
   const root = "/app";
@@ -165,6 +296,37 @@ export default { GetUsers };
     });
   });
 
+  it("emits a bare entry and invokes onExtractionError when the API file read throws", async () => {
+    const registryContent = `
+import GetUsers from './GetUsers/api.js';
+export default { GetUsers };
+`;
+    const readError = new Error("source unreadable");
+    const readFile = vi.fn(async (filePath: string) => {
+      const rel = path.relative(root, filePath).replace(/\\/g, "/");
+      if (rel === "server/apis/index.ts") {
+        return registryContent;
+      }
+      throw readError;
+    });
+    const onExtractionError = vi.fn();
+
+    const result = await collectSdkApisFromRegistry(
+      root,
+      { pathExists, readFile },
+      { onExtractionError },
+    );
+
+    expect(result).toEqual({
+      GetUsers: { entryPoint: "server/apis/GetUsers/api.ts" },
+    });
+    expect(onExtractionError).toHaveBeenCalledWith(
+      "GetUsers",
+      "server/apis/GetUsers/api.ts",
+      readError,
+    );
+  });
+
   it("reads from server/apis/index.ts relative to root", async () => {
     const readFile = vi
       .fn()
@@ -182,4 +344,221 @@ export default { GetUsers };
       "utf-8",
     );
   });
+
+  it("resolves integrations imported from shared modules into the manifest", async () => {
+    const files: Record<string, string> = {
+      "server/apis/index.ts": `
+        import CreateIssue from "./create-issue.js";
+        const apis = { CreateIssue } as const;
+        export default apis;
+      `,
+      "server/apis/create-issue.ts": `
+        import { api } from "@superblocksteam/sdk-api";
+        import { jira } from "../lib/integrations.js";
+        export default api({ integrations: { jira } });
+      `,
+      "server/lib/integrations.ts": `
+        import { restApiIntegration } from "@superblocksteam/sdk-api";
+        export const jira = restApiIntegration("jira-uuid");
+      `,
+    };
+    const rel = (p: string) => path.relative(root, p).replace(/\\/g, "/");
+
+    const result = await collectSdkApisFromRegistry(root, {
+      pathExists: async (p) => rel(p) in files,
+      readFile: async (p) => {
+        const source = files[rel(p)];
+        if (source === undefined) {
+          throw new Error(`missing: ${p}`);
+        }
+        return source;
+      },
+    });
+
+    expect(result.CreateIssue.integrations).toEqual([
+      { key: "jira", pluginId: "restApiIntegration", id: "jira-uuid" },
+    ]);
+    expect(result.CreateIssue.unresolvedIntegrations).toBeUndefined();
+  });
+
+  it("records unresolved integrations and reports them through the callback", async () => {
+    const files: Record<string, string> = {
+      "server/apis/index.ts": `
+        import CreateIssue from "./create-issue.js";
+        const apis = { CreateIssue } as const;
+        export default apis;
+      `,
+      "server/apis/create-issue.ts": `
+        import { api } from "@superblocksteam/sdk-api";
+        import { jira } from "missing-package";
+        export default api({ integrations: { jira } });
+      `,
+    };
+    const rel = (p: string) => path.relative(root, p).replace(/\\/g, "/");
+    const onUnresolvedIntegrations = vi.fn();
+
+    const result = await collectSdkApisFromRegistry(
+      root,
+      {
+        pathExists: async (p) => rel(p) in files,
+        readFile: async (p) => {
+          const source = files[rel(p)];
+          if (source === undefined) {
+            throw new Error(`missing: ${p}`);
+          }
+          return source;
+        },
+      },
+      { onUnresolvedIntegrations },
+    );
+
+    expect(result.CreateIssue.integrations).toBeUndefined();
+    expect(result.CreateIssue.unresolvedIntegrations).toEqual(["jira"]);
+    expect(onUnresolvedIntegrations).toHaveBeenCalledWith(
+      "CreateIssue",
+      "server/apis/create-issue.ts",
+      ["jira"],
+    );
+  });
+
+  it("marks the entry as unresolved and reports it when the API file source fails to parse", async () => {
+    // A parse failure on the entry file itself (e.g. parser-config drift —
+    // syntax the real build compiles but our @babel/parser config rejects)
+    // must not recreate the silent check-auth gap: the entry should carry
+    // unresolvedIntegrations: ["*"] and onUnresolvedIntegrations must fire,
+    // exactly as for any other unresolvable integrations surface.
+    const files: Record<string, string> = {
+      "server/apis/index.ts": `
+        import CreateIssue from "./create-issue.js";
+        const apis = { CreateIssue } as const;
+        export default apis;
+      `,
+      "server/apis/create-issue.ts": `export default api({ integrations: {`,
+    };
+    const rel = (p: string) => path.relative(root, p).replace(/\\/g, "/");
+    const onUnresolvedIntegrations = vi.fn();
+    const onExtractionError = vi.fn();
+
+    const result = await collectSdkApisFromRegistry(
+      root,
+      {
+        pathExists: async (p) => rel(p) in files,
+        readFile: async (p) => {
+          const source = files[rel(p)];
+          if (source === undefined) {
+            throw new Error(`missing: ${p}`);
+          }
+          return source;
+        },
+      },
+      { onUnresolvedIntegrations, onExtractionError },
+    );
+
+    expect(result.CreateIssue).toEqual({
+      entryPoint: "server/apis/create-issue.ts",
+      unresolvedIntegrations: ["*"],
+    });
+    expect(onUnresolvedIntegrations).toHaveBeenCalledWith(
+      "CreateIssue",
+      "server/apis/create-issue.ts",
+      ["*"],
+    );
+    expect(onExtractionError).not.toHaveBeenCalled();
+  });
+
+  it("never queries the filesystem outside root for a backslash import specifier", async () => {
+    // Backslash import specifiers are a known Windows path-traversal vector:
+    // the extractor's posix-only containment check doesn't catch them, but
+    // the collector's own readSource containment guard (defense in depth)
+    // must still refuse to touch anything outside root. `\\\\` is needed
+    // (not `\\`) so a literal single backslash survives being unescaped
+    // twice: once by this outer template literal, once by the parser that
+    // reads the fixture source under test.
+    const files: Record<string, string> = {
+      "server/apis/index.ts": `
+        import Leak from './leak.js';
+        const apis = { Leak } as const;
+        export default apis;
+      `,
+      "server/apis/leak.ts": `
+        import { api, restApiIntegration } from "@superblocksteam/sdk-api";
+        import { SECRET } from "..\\\\..\\\\..\\\\secret.js";
+        export default api({ integrations: { leak: restApiIntegration(SECRET) } });
+      `,
+    };
+    const rel = (p: string) => path.relative(root, p).replace(/\\/g, "/");
+    const pathExists = vi.fn(async (p: string) => rel(p) in files);
+
+    const result = await collectSdkApisFromRegistry(root, {
+      pathExists,
+      readFile: async (p) => {
+        const source = files[rel(p)];
+        if (source === undefined) {
+          throw new Error(`missing: ${p}`);
+        }
+        return source;
+      },
+    });
+
+    expect(result.Leak.integrations).toBeUndefined();
+    expect(result.Leak.unresolvedIntegrations).toEqual(["leak"]);
+    // The extractor must never hand the collector a candidate derived from
+    // the backslash specifier in the first place (that candidate would
+    // itself still contain a backslash once joined). This is what actually
+    // distinguishes fixed from unfixed here: on a POSIX test runner,
+    // path.join treats a stray backslash as an ordinary filename character,
+    // so a resolved-outside-root assertion alone would pass even without
+    // either fix.
+    for (const call of pathExists.mock.calls) {
+      expect(call[0] as string).not.toContain("\\");
+    }
+  });
+
+  it("does not read a file whose canonical (real) path escapes root, even though the lexical path is in-root", async () => {
+    // server/lib/integrations.ts exists lexically inside root (it passes
+    // pathExists and the lexical containment check), but it is a symlink
+    // whose canonical target resolves outside root. Without realpath
+    // canonicalization, readSource would happily read through the symlink.
+    const files: Record<string, string> = {
+      "server/apis/index.ts": `
+        import CreateIssue from "./create-issue.js";
+        const apis = { CreateIssue } as const;
+        export default apis;
+      `,
+      "server/apis/create-issue.ts": `
+        import { api } from "@superblocksteam/sdk-api";
+        import { jira } from "../lib/integrations.js";
+        export default api({ integrations: { jira } });
+      `,
+      "server/lib/integrations.ts": `
+        import { restApiIntegration } from "@superblocksteam/sdk-api";
+        export const jira = restApiIntegration("jira-uuid");
+      `,
+    };
+    const rel = (p: string) => path.relative(root, p).replace(/\\/g, "/");
+    const escapingRealPath = "/etc/evil-integrations.ts";
+    const escapingLexicalPath = path.join(root, "server/lib/integrations.ts");
+
+    const readFile = vi.fn(async (p: string) => {
+      const source = files[rel(p)];
+      if (source === undefined) {
+        throw new Error(`missing: ${p}`);
+      }
+      return source;
+    });
+    const realpath = vi.fn(async (p: string) =>
+      p === escapingLexicalPath ? escapingRealPath : p,
+    );
+
+    const result = await collectSdkApisFromRegistry(root, {
+      pathExists: async (p) => rel(p) in files,
+      readFile,
+      realpath,
+    });
+
+    expect(result.CreateIssue.integrations).toBeUndefined();
+    expect(result.CreateIssue.unresolvedIntegrations).toEqual(["jira"]);
+    expect(readFile).not.toHaveBeenCalledWith(escapingRealPath, "utf-8");
+    expect(readFile).not.toHaveBeenCalledWith(escapingLexicalPath, "utf-8");
+  });
 });