[managed credentials 01/17] SDK managed credential request and session contracts

.changeset/managed-credentials-sdk-contracts.md

@@ -0,0 +1,5 @@
+---
+"@vercel/sandbox": minor
+---
+
+Add managed Git and GitHub API credential request contracts and optional nonsecret session request metadata. Disable creation retries to avoid duplicate Sandboxes and grants after uncertain responses.

.changeset/managed-sdk-mock-exports-fix.md

@@ -0,0 +1,5 @@
+---
+"@vercel/sandbox-mock": patch
+---
+
+Re-export managed credential action constants and types to keep the mock package compatible with the real SDK.

packages/vercel-sandbox-mock/src/index.ts

@@ -18,6 +18,8 @@ export type {
 // The rest of the SDK surface, re-exported verbatim from the real package.
 export {
   DEFAULT_SANDBOX_REGION,
+  GITHUB_API_CREDENTIAL_ACTIONS,
+  MANAGED_GIT_ACTIONS,
   Session,
   SandboxUser,
   SandboxUserAlreadyExistsError,
@@ -31,6 +33,8 @@ export {
   NetworkPolicyParseError,
 } from "@vercel/sandbox";
 export type {
+  ManagedGitAction,
+  ManagedSourceCredentials,
   NetworkPolicy,
   NetworkPolicyKeyValueMatcher,
   NetworkPolicyMatch,

packages/vercel-sandbox-mock/tests/package-exports.test.ts

@@ -10,6 +10,16 @@ import {
 } from "@vercel/sandbox";
 
 describe("public exports", () => {
+  test("re-exports managed credential action constants unchanged", () => {
+    expect(mock).toHaveProperty(
+      "GITHUB_API_CREDENTIAL_ACTIONS",
+      real.GITHUB_API_CREDENTIAL_ACTIONS,
+    );
+    expect(mock).toHaveProperty(
+      "MANAGED_GIT_ACTIONS",
+      real.MANAGED_GIT_ACTIONS,
+    );
+  });
   test("re-exports every value the real SDK exposes", () => {
     const realValues = Object.keys(real).filter(
       (key) => typeof (real as Record<string, unknown>)[key] !== "undefined",

packages/vercel-sandbox/src/api-client/api-client.ts

@@ -47,6 +47,10 @@ import type { SandboxMetaData } from "./validators.js";
 import { withRetry } from "./with-retry.js";
 import { setTimeout as delay } from "node:timers/promises";
 import { StringDecoder } from "node:string_decoder";
+import type {
+  ManagedCredentialOptions,
+  ManagedSourceCredentials,
+} from "../managed-credentials.js";
 
 const STDIN_MAX_RETRIES = 5;
 const STDIN_MAX_STALLED_TIMEOUTS = 2;
@@ -228,41 +232,44 @@ export class APIClient extends BaseClient {
   }
 
   async createSandbox(
-    params: WithPrivate<{
-      name?: string;
-      ports?: number[];
-      projectId: string;
-      source?:
-        | {
-            type: "git";
-            url: string;
-            depth?: number;
-            revision?: string;
-            username?: string;
-            password?: string;
-          }
-        | { type: "tarball"; url: string }
-        | { type: "snapshot"; snapshotId: string };
-      timeout?: number;
-      resources?: { vcpus: number };
-      persistent?: boolean;
-      runtime?: RUNTIMES | (string & {});
-      image?: string;
-      networkPolicy?: NetworkPolicy;
-      networkId?: string;
-      env?: Record<string, string>;
-      tags?: Record<string, string>;
-      snapshotExpiration?: number;
-      keepLastSnapshots?: {
-        count: number;
-        expiration?: number;
-        deleteEvicted?: boolean;
-      };
-      mounts?: SandboxMetaData["mounts"];
-      region?: SandboxRegion;
-      failoverRegions?: SandboxRegion[];
-      signal?: AbortSignal;
-    }>,
+    params: WithPrivate<
+      ManagedCredentialOptions & {
+        name?: string;
+        ports?: number[];
+        projectId: string;
+        source?:
+          | {
+              type: "git";
+              url: string;
+              depth?: number;
+              revision?: string;
+              username?: string;
+              password?: string;
+              credentials?: ManagedSourceCredentials;
+            }
+          | { type: "tarball"; url: string }
+          | { type: "snapshot"; snapshotId: string };
+        timeout?: number;
+        resources?: { vcpus: number };
+        persistent?: boolean;
+        runtime?: RUNTIMES | (string & {});
+        image?: string;
+        networkPolicy?: NetworkPolicy;
+        networkId?: string;
+        env?: Record<string, string>;
+        tags?: Record<string, string>;
+        snapshotExpiration?: number;
+        keepLastSnapshots?: {
+          count: number;
+          expiration?: number;
+          deleteEvicted?: boolean;
+        };
+        mounts?: SandboxMetaData["mounts"];
+        region?: SandboxRegion;
+        failoverRegions?: SandboxRegion[];
+        signal?: AbortSignal;
+      }
+    >,
   ) {
     const privateParams = getPrivateParams(params);
     const endpoint =
@@ -271,10 +278,14 @@ export class APIClient extends BaseClient {
       SandboxAndSessionResponse,
       await this.request(endpoint, {
         method: "POST",
+        // An uncertain response must not create another Sandbox or grant.
+        retry: { retries: 0 },
         body: JSON.stringify({
           projectId: params.projectId,
           ports: params.ports,
           source: params.source,
+          commitAs: params.commitAs,
+          credentials: params.credentials,
           timeout: params.timeout,
           resources: params.resources,
           runtime: params.runtime,

packages/vercel-sandbox/src/api-client/validators.ts

@@ -134,7 +134,33 @@ export const NetworkPolicyResponseValidator = z.union([
   LegacyCustomNetworkPolicyValidator,
 ]);
 
+/** Nonsecret requested configuration; never tokens, grants, or consent. */
+export const ManagedCredentialsResponseValidator = z.object({
+  source: z
+    .object({
+      type: z.literal("git"),
+      url: z.string(),
+      revision: z.string().optional(),
+      depth: z.number().optional(),
+      credentials: z.union([z.literal(true), z.literal("read")]).optional(),
+    })
+    .optional(),
+  commitAs: z.object({ name: z.string(), email: z.string() }).optional(),
+  credentials: z
+    .object({
+      github: z.array(
+        z.object({
+          repositories: z.array(z.string()),
+          actions: z.array(z.string()),
+          actAs: z.union([z.string(), z.number()]).optional(),
+        }),
+      ),
+    })
+    .optional(),
+});
+
 export const Session = z.object({
+  managedCredentials: ManagedCredentialsResponseValidator.optional(),
   id: z.string(),
   memory: z.number(),
   vcpus: z.number(),

packages/vercel-sandbox/src/index.ts

@@ -16,6 +16,14 @@ export type { SerializedSandbox } from "./sandbox.js";
 export { SandboxUser, SandboxUserAlreadyExistsError } from "./sandbox-user.js";
 export type { ExecutionContext } from "./execution-context.js";
 export { DEFAULT_SANDBOX_REGION } from "./constants.js";
+export {
+  GITHUB_API_CREDENTIAL_ACTIONS,
+  MANAGED_GIT_ACTIONS,
+} from "./managed-credentials.js";
+export type {
+  ManagedGitAction,
+  ManagedSourceCredentials,
+} from "./managed-credentials.js";
 export type { SandboxRegion } from "./constants.js";
 export { Snapshot } from "./snapshot.js";
 export type { SerializedSnapshot } from "./snapshot.js";