run402 1.54.4 → 1.55.0

package/README.md

@@ -62,6 +62,34 @@ run402 subdomains claim my-app                # → my-app.run402.com (auto-reas
 
 `deploy-dir` hashes each file client-side and only uploads bytes the gateway doesn't already have. Re-deploying an unchanged tree returns immediately with `bytes_uploaded: 0`. Progress events stream to stderr.
 
+### GitHub Actions OIDC deploys
+
+Link once from a local shell that has your Run402 allowance, then commit the generated workflow and manifest:
+
+```bash
+run402 ci link github --project prj_... --manifest run402.deploy.json
+run402 ci list --project prj_...
+run402 ci revoke cib_...
+```
+
+`link github` infers `owner/repo` and the current branch, verifies the numeric GitHub repository id, creates a deploy-scoped CI binding, and writes `.github/workflows/run402-deploy.yml` unless you pass `--workflow`. The generated workflow is intentionally just the existing deploy command with OIDC enabled:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Deploy to run402
+        run: npx --yes run402@1.54.4 deploy apply --manifest 'run402.deploy.json' --project 'prj_...'
+```
+
+CI deploys can ship `site`, `functions`, and `database` changes. Keep secrets, domains, subdomains, routes, checks, and non-current base changes in a local `run402 deploy apply` where the full allowance-backed authority is present.
+
 ### Storage (paste-and-go CDN assets)
 
 ```bash

package/cli.mjs

@@ -26,6 +26,7 @@ Commands:
   tier        Manage tier subscription (status, set)
   projects    Manage projects (provision, list, query, inspect, delete)
   deploy      Deploy a full-stack app or static site (requires active tier)
+  ci          Link GitHub Actions OIDC deploy bindings
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)
   secrets     Manage project secrets (set, list, delete)
   blob        Direct-to-S3 blob storage (put, get, ls, rm, sign, diagnose) — up to 5 TiB
@@ -62,6 +63,7 @@ Getting started:
   run402 init mpp           Set up with MPP (Tempo Moderato)
   run402 tier set prototype  Subscribe to a tier
   run402 deploy --manifest app.json
+  run402 ci link github --project prj_... --manifest run402.deploy.json
 `;
 
 if (cmd === '--version' || cmd === '-v') {
@@ -122,6 +124,11 @@ switch (cmd) {
     await run([sub, ...rest].filter(Boolean));
     break;
   }
+  case "ci": {
+    const { run } = await import("./lib/ci.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "functions": {
     const { run } = await import("./lib/functions.mjs");
     await run(sub, rest);

package/core-dist/allowance-auth.js

@@ -70,16 +70,44 @@ export function formatSIWEMessage(opts, address) {
         opts.statement,
         "",
         `URI: ${opts.uri}`,
-        `Version: ${opts.version}`,
-        `Chain ID: ${opts.chainId}`,
+        `Version: ${opts.version ?? "1"}`,
+        `Chain ID: ${messageChainId(opts.chainId)}`,
         `Nonce: ${opts.nonce}`,
         `Issued At: ${opts.issuedAt}`,
     ];
     if (opts.expirationTime) {
         lines.push(`Expiration Time: ${opts.expirationTime}`);
     }
+    if (opts.resources && opts.resources.length > 0) {
+        lines.push("Resources:");
+        for (const resource of opts.resources)
+            lines.push(`- ${resource}`);
+    }
     return lines.join("\n");
 }
+export function buildSIWxAuthHeaders(opts) {
+    const message = formatSIWEMessage(opts, opts.allowance.address);
+    const signature = personalSign(opts.allowance.privateKey, opts.allowance.address, message);
+    const payload = {
+        domain: opts.domain,
+        address: toChecksumAddress(opts.allowance.address),
+        statement: opts.statement,
+        uri: opts.uri,
+        version: opts.version ?? "1",
+        chainId: payloadChainId(opts.chainId),
+        type: opts.type ?? "eip191",
+        nonce: opts.nonce,
+        issuedAt: opts.issuedAt,
+        expirationTime: opts.expirationTime,
+        signature,
+    };
+    if (opts.resources !== undefined) {
+        payload.resources = opts.resources;
+    }
+    return {
+        "SIGN-IN-WITH-X": Buffer.from(JSON.stringify(payload)).toString("base64"),
+    };
+}
 /**
  * Get SIWX auth headers for the Run402 API.
  * Returns null if no allowance is configured.
@@ -103,32 +131,24 @@ export function getAllowanceAuthHeaders(path, allowancePath) {
     const now = new Date();
     const issuedAt = now.toISOString();
     const expirationTime = new Date(now.getTime() + 5 * 60 * 1000).toISOString();
-    const message = formatSIWEMessage({
+    return buildSIWxAuthHeaders({
+        allowance,
         domain,
         uri,
         statement: "Sign in to Run402",
-        version: "1",
-        chainId: 84532, // Base Sepolia
-        nonce,
-        issuedAt,
-        expirationTime,
-    }, allowance.address);
-    const signature = personalSign(allowance.privateKey, allowance.address, message);
-    const payload = {
-        domain,
-        address: toChecksumAddress(allowance.address),
-        statement: "Sign in to Run402",
-        uri,
-        version: "1",
         chainId: "eip155:84532",
-        type: "eip191",
         nonce,
         issuedAt,
         expirationTime,
-        signature,
-    };
-    return {
-        "SIGN-IN-WITH-X": Buffer.from(JSON.stringify(payload)).toString("base64"),
-    };
+    });
+}
+function messageChainId(chainId) {
+    if (typeof chainId === "number")
+        return String(chainId);
+    const match = /^eip155:(\d+)$/.exec(chainId);
+    return match ? match[1] : chainId;
+}
+function payloadChainId(chainId) {
+    return typeof chainId === "number" ? `eip155:${chainId}` : chainId;
 }
 //# sourceMappingURL=allowance-auth.js.map

package/lib/ci.mjs

@@ -0,0 +1,395 @@
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  CI_GITHUB_ACTIONS_PROVIDER,
+  DEFAULT_CI_DELEGATION_CHAIN_ID,
+  V1_CI_ALLOWED_ACTIONS,
+  V1_CI_ALLOWED_EVENTS_DEFAULT,
+  signCiDelegation,
+} from "#sdk/node";
+import { API, resolveProjectId } from "./config.mjs";
+import { getSdk } from "./sdk.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
+
+const { version: RUN402_VERSION } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+const HELP = `run402 ci — Manage CI/OIDC deploy bindings
+
+Usage:
+  run402 ci link github [--project <id>] [--manifest <path>] [--repo <owner/repo>] [--branch <name> | --environment <name>] [--repository-id <id>] [--workflow <path>] [--expires-at <iso>] [--force]
+  run402 ci list [--project <id>]
+  run402 ci revoke <binding_id>
+
+Subcommands:
+  link github   Link this repo/branch or environment for GitHub Actions deploys
+  list          List CI bindings for a project
+  revoke        Revoke a CI binding
+`;
+
+const SUB_HELP = {
+  link: `run402 ci link github — Link GitHub Actions OIDC for deploy apply
+
+Usage:
+  run402 ci link github [--project <id>] [--manifest <path>] [--repo <owner/repo>] [--branch <name> | --environment <name>] [--repository-id <id>] [--workflow <path>] [--expires-at <iso>] [--force]
+
+Options:
+  --project <id>          Project ID (defaults to the active project)
+  --manifest <path>       Manifest path used by the generated workflow (default: run402.deploy.json)
+  --repo <owner/repo>     GitHub repo (default: inferred from origin remote)
+  --branch <name>         Branch subject and push trigger (default: current branch)
+  --environment <name>    GitHub environment subject; adds job.environment
+  --repository-id <id>    Numeric GitHub repository id when API lookup is unavailable
+  --workflow <path>       Workflow path (default: .github/workflows/run402-deploy.yml)
+  --expires-at <iso>      Optional binding expiration timestamp
+  --force                 Overwrite an existing workflow file
+
+Notes:
+  - v1 allows only push and workflow_dispatch events.
+  - v1 does not expose raw subject, wildcard, or pull-request deploy flags.
+`,
+  list: `run402 ci list — List CI bindings
+
+Usage:
+  run402 ci list [--project <id>]
+`,
+  revoke: `run402 ci revoke — Revoke a CI binding
+
+Usage:
+  run402 ci revoke <binding_id>
+`,
+};
+
+function parseFlags(args, allowed) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    if (!allowed.has(arg)) {
+      fail({
+        code: "BAD_USAGE",
+        message: `Unsupported flag: ${arg}`,
+        hint: "Run: run402 ci link github --help",
+        details: { flag: arg },
+      });
+    }
+    if (arg === "--force") {
+      flags.force = true;
+      continue;
+    }
+    if (!args[i + 1] || args[i + 1].startsWith("--")) {
+      fail({
+        code: "BAD_USAGE",
+        message: `Missing value for ${arg}.`,
+        details: { flag: arg },
+      });
+    }
+    flags[arg.slice(2).replace(/-/g, "_")] = args[++i];
+  }
+  return { flags, positional };
+}
+
+function rejectHighRiskFlags(args) {
+  const blocked = [
+    "--subject",
+    "--subject-match",
+    "--wildcard",
+    "--allow-event",
+    "--event",
+    "--pull-request",
+    "--pr",
+    "--no-repository-id",
+  ];
+  const hit = args.find((arg) => blocked.includes(arg));
+  if (hit) {
+    fail({
+      code: "UNSUPPORTED_CI_FLAG",
+      message: `${hit} is intentionally not exposed by run402 ci link github v1.`,
+      hint: "Use --branch or --environment. PR deploys, raw subjects, wildcards, and soft repository-id binding are deferred.",
+      details: { flag: hit },
+    });
+  }
+}
+
+function git(args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function inferRepo() {
+  const remote = git(["remote", "get-url", "origin"]);
+  if (!remote) return null;
+  return parseGithubRemote(remote);
+}
+
+function parseGithubRemote(remote) {
+  const cleaned = remote.trim().replace(/\.git$/, "");
+  const ssh = cleaned.match(/^git@github\.com:([^/]+)\/(.+)$/);
+  if (ssh) return `${ssh[1]}/${ssh[2]}`;
+  const https = cleaned.match(/^https:\/\/github\.com\/([^/]+)\/(.+)$/);
+  if (https) return `${https[1]}/${https[2]}`;
+  const sshUrl = cleaned.match(/^ssh:\/\/git@github\.com\/([^/]+)\/(.+)$/);
+  if (sshUrl) return `${sshUrl[1]}/${sshUrl[2]}`;
+  return null;
+}
+
+function inferBranch() {
+  return git(["branch", "--show-current"]);
+}
+
+async function fetchGithubRepositoryId(repo) {
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  const headers = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "run402-cli",
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  let res;
+  try {
+    res = await fetch(`https://api.github.com/repos/${repo}`, { headers });
+  } catch {
+    return null;
+  }
+  const body = await res.json().catch(() => null);
+  if (!res.ok || typeof body?.id !== "number") return null;
+  return String(body.id);
+}
+
+function buildSubject(repo, { branch, environment }) {
+  if (environment) return `repo:${repo}:environment:${environment}`;
+  if (!branch) {
+    fail({
+      code: "CI_SUBJECT_REQUIRED",
+      message: "Could not infer a branch for the GitHub Actions subject.",
+      hint: "Pass --branch <name> or --environment <name>.",
+    });
+  }
+  return `repo:${repo}:ref:refs/heads/${branch}`;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function yamlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function generateWorkflow({ branch, environment, manifest, projectId }) {
+  const pushBlock = branch
+    ? `  push:\n    branches: [${yamlString(branch)}]\n`
+    : `  push:\n`;
+  const environmentLine = environment ? `    environment: ${yamlString(environment)}\n` : "";
+  return `name: Run402 Deploy
+
+on:
+${pushBlock}  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+${environmentLine}    steps:
+      - uses: actions/checkout@v4
+      - name: Deploy to run402
+        run: npx --yes run402@${RUN402_VERSION} deploy apply --manifest ${shellQuote(manifest)} --project ${shellQuote(projectId)}
+`;
+}
+
+async function linkGithub(args) {
+  rejectHighRiskFlags(args);
+  const { flags, positional } = parseFlags(args, new Set([
+    "--project",
+    "--manifest",
+    "--repo",
+    "--branch",
+    "--environment",
+    "--repository-id",
+    "--workflow",
+    "--expires-at",
+    "--force",
+  ]));
+  if (positional[0] !== "github" || positional.length > 1) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing provider: github.",
+      hint: "run402 ci link github [--project <id>]",
+    });
+  }
+  if (flags.branch && flags.environment) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Choose either --branch or --environment, not both.",
+    });
+  }
+
+  const projectId = resolveProjectId(flags.project);
+  const repo = flags.repo || inferRepo();
+  if (!repo || !/^[^/\s]+\/[^/\s]+$/.test(repo)) {
+    fail({
+      code: "GITHUB_REPO_REQUIRED",
+      message: "Could not infer GitHub owner/repo from git remote origin.",
+      hint: "Pass --repo <owner/repo>.",
+    });
+  }
+  const branch = flags.environment ? (flags.branch || inferBranch() || null) : (flags.branch || inferBranch());
+  const subject = buildSubject(repo, { branch, environment: flags.environment });
+  const repositoryId = flags.repository_id || await fetchGithubRepositoryId(repo);
+  if (!repositoryId) {
+    fail({
+      code: "GITHUB_REPOSITORY_ID_REQUIRED",
+      message: `Could not fetch the numeric GitHub repository id for ${repo}.`,
+      hint: "Set GITHUB_TOKEN/GH_TOKEN or pass --repository-id <id>.",
+      details: { repo },
+    });
+  }
+
+  const workflowPath = flags.workflow || ".github/workflows/run402-deploy.yml";
+  const absWorkflowPath = resolve(process.cwd(), workflowPath);
+  if (existsSync(absWorkflowPath) && !flags.force) {
+    fail({
+      code: "WORKFLOW_EXISTS",
+      message: `Workflow already exists: ${workflowPath}`,
+      hint: "Pass --force to overwrite it.",
+      details: { workflow_path: workflowPath },
+    });
+  }
+
+  const manifest = flags.manifest || "run402.deploy.json";
+  const nonce = randomBytes(16).toString("hex");
+  const values = {
+    project_id: projectId,
+    subject_match: subject,
+    allowed_actions: V1_CI_ALLOWED_ACTIONS,
+    allowed_events: V1_CI_ALLOWED_EVENTS_DEFAULT,
+    github_repository_id: repositoryId,
+    expires_at: flags.expires_at || null,
+    nonce,
+  };
+
+  let signedDelegation;
+  try {
+    signedDelegation = signCiDelegation(values, { apiBase: API });
+  } catch (err) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: err?.message || "No local allowance configured.",
+      hint: "Run: run402 init",
+    });
+  }
+
+  const workflow = generateWorkflow({
+    branch,
+    environment: flags.environment || null,
+    manifest,
+    projectId,
+  });
+
+  try {
+    const binding = await getSdk({ disablePaidFetch: true }).ci.createBinding({
+      ...values,
+      provider: CI_GITHUB_ACTIONS_PROVIDER,
+      signed_delegation: signedDelegation,
+    });
+    mkdirSync(dirname(absWorkflowPath), { recursive: true });
+    writeFileSync(absWorkflowPath, workflow, { encoding: "utf8", mode: 0o644 });
+    console.log(JSON.stringify({
+      status: "ok",
+      binding_id: binding.id,
+      project_id: projectId,
+      provider: CI_GITHUB_ACTIONS_PROVIDER,
+      subject_match: subject,
+      allowed_events: [...V1_CI_ALLOWED_EVENTS_DEFAULT],
+      allowed_actions: [...V1_CI_ALLOWED_ACTIONS],
+      github_repository_id: repositoryId,
+      github_repository_id_status: flags.repository_id ? "provided" : "verified",
+      workflow_path: workflowPath,
+      manifest_path: manifest,
+      run402_version: RUN402_VERSION,
+      delegation_chain_id: DEFAULT_CI_DELEGATION_CHAIN_ID,
+      bootstrap_caveat: "Commit the generated workflow and manifest before expecting GitHub Actions deploys.",
+      consent_summary: [
+        "This binding lets matching GitHub Actions workflows deploy site, function, and database changes to the project.",
+        "It does not allow direct secrets, domains, subdomains, lifecycle, billing, contracts, or faucet API calls.",
+      ],
+      revocation_residuals: [
+        "Revocation stops future CI gateway requests.",
+        "Revocation does not undo already-deployed code, stop in-flight deploy operations, rotate exfiltrated keys, or remove deployed functions.",
+      ],
+    }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function list(args) {
+  const { flags } = parseFlags(args, new Set(["--project"]));
+  const project = resolveProjectId(flags.project);
+  try {
+    const result = await getSdk({ disablePaidFetch: true }).ci.listBindings({ project });
+    console.log(JSON.stringify({ status: "ok", project_id: project, ...result }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function revoke(args) {
+  const bindingId = args.find((arg) => !arg.startsWith("--"));
+  if (!bindingId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <binding_id>.",
+      hint: "run402 ci revoke <binding_id>",
+    });
+  }
+  try {
+    const binding = await getSdk({ disablePaidFetch: true }).ci.revokeBinding(bindingId);
+    console.log(JSON.stringify({
+      status: "ok",
+      binding,
+      revocation_residuals: [
+        "Revocation stops future CI gateway requests.",
+        "Revocation does not undo already-deployed code, stop in-flight deploy operations, rotate exfiltrated keys, or remove deployed functions.",
+      ],
+    }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(HELP);
+    process.exit(0);
+  }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
+    console.log(SUB_HELP[sub] || HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "link": await linkGithub(args); break;
+    case "list": await list(args); break;
+    case "revoke": await revoke(args); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/deploy-v2.mjs

@@ -25,9 +25,10 @@
 
 import { readFileSync } from "node:fs";
 import { resolve, dirname, isAbsolute, join } from "node:path";
+import { githubActionsCredentials } from "#sdk/node";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { allowanceAuthHeaders, resolveProjectId } from "./config.mjs";
+import { API, allowanceAuthHeaders, getActiveProjectId, resolveProjectId } from "./config.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
 
@@ -213,7 +214,10 @@ async function applyCmd(args) {
     });
   }
   if (opts.project) spec.project_id = opts.project;
-  if (!spec.project_id) spec.project_id = resolveProjectId(null);
+  const useGithubActionsOidc = hasGithubActionsOidcEnv();
+  if (!spec.project_id) {
+    spec.project_id = useGithubActionsOidc ? resolveCiProjectId() : resolveProjectId(null);
+  }
 
   // Translate { project_id, ... } envelope → ReleaseSpec ({ project, ... })
   // The SDK ReleaseSpec uses `project` rather than `project_id`; both shapes
@@ -222,18 +226,123 @@ async function applyCmd(args) {
   const releaseSpec = mapManifestToReleaseSpec(spec);
   const idempotencyKey = spec.idempotency_key;
 
-  // Preserve the aggressive early exit when no allowance is configured.
-  allowanceAuthHeaders("/deploy/v2/plans");
+  let sdkOpts;
+  if (useGithubActionsOidc) {
+    sdkOpts = {
+      credentials: githubActionsCredentials({ projectId: spec.project_id, apiBase: API }),
+      disablePaidFetch: true,
+    };
+  } else {
+    // Preserve the aggressive early exit when no allowance is configured.
+    allowanceAuthHeaders("/deploy/v2/plans");
+  }
 
   try {
-    const result = await getSdk().deploy.apply(releaseSpec, {
+    const result = await getSdk(sdkOpts).deploy.apply(releaseSpec, {
       onEvent: makeStderrEventWriter(opts.quiet),
       idempotencyKey,
     });
     console.log(JSON.stringify({ status: "ok", ...result }, null, 2));
   } catch (err) {
-    reportSdkError(err);
+    reportDeployApplyError(err, useGithubActionsOidc);
+  }
+}
+
+function hasGithubActionsOidcEnv(env = process.env) {
+  return env.GITHUB_ACTIONS === "true" &&
+    Boolean(env.ACTIONS_ID_TOKEN_REQUEST_URL) &&
+    Boolean(env.ACTIONS_ID_TOKEN_REQUEST_TOKEN);
+}
+
+function resolveCiProjectId(env = process.env) {
+  const projectId = getActiveProjectId() || env.RUN402_PROJECT_ID;
+  if (!projectId) {
+    fail({
+      code: "CI_PROJECT_REQUIRED",
+      message: "GitHub Actions OIDC deploy requires a project id.",
+      hint: "Pass --project <prj_...> in the workflow command, include project_id in the manifest, or set RUN402_PROJECT_ID.",
+      details: { sources: ["--project", "manifest.project_id", "active_project", "RUN402_PROJECT_ID"] },
+    });
   }
+  return projectId;
+}
+
+const CI_DEPLOY_ERROR_GUIDANCE = {
+  invalid_token: {
+    hint: "Ensure the workflow has permissions: id-token: write and is running in the repository/branch linked with run402 ci link github.",
+    next_actions: [
+      "Check the workflow permissions block includes id-token: write.",
+      "Re-run run402 ci link github if the repository, branch, or environment changed.",
+    ],
+  },
+  access_denied: {
+    hint: "The OIDC token was valid, but no active Run402 CI binding allowed this workflow.",
+    next_actions: [
+      "Run run402 ci list --project <prj_...> locally to inspect bindings.",
+      "Run run402 ci link github again for this repository/branch/environment.",
+    ],
+  },
+  event_not_allowed: {
+    hint: "This binding only allows push and workflow_dispatch events in v1.",
+    next_actions: [
+      "Trigger the workflow with push or workflow_dispatch.",
+      "Create a separate follow-up design before enabling PR deploy events.",
+    ],
+  },
+  repository_id_mismatch: {
+    hint: "The GitHub repository id in the OIDC token does not match the linked binding.",
+    next_actions: [
+      "Run run402 ci link github again from the current repository.",
+      "If automatic lookup fails, pass --repository-id with the numeric GitHub repository id.",
+    ],
+  },
+  forbidden_spec_field: {
+    hint: "CI deploys in v1 can deploy site/functions/database content only; link locally for secrets, routes, subdomains, checks, or oversized manifests.",
+    next_actions: [
+      "Remove forbidden fields such as secrets, routes, subdomains, or checks from the CI manifest.",
+      "Keep the normalized manifest small enough to avoid manifest_ref.",
+    ],
+  },
+  forbidden_plan: {
+    hint: "The gateway rejected this deploy plan for CI. Keep CI deploys to the v1 allowed resources and re-link if policy changed.",
+    next_actions: [
+      "Inspect the gateway error details for the rejected resource.",
+      "Run the deploy locally with run402 deploy apply for operations outside the CI allowlist.",
+    ],
+  },
+  payment_required: {
+    hint: "The project tier or payment state does not allow this CI deploy.",
+    next_actions: [
+      "Run run402 tier status --project <prj_...> locally.",
+      "Renew or upgrade the project tier, then re-run the workflow.",
+    ],
+  },
+};
+
+function reportDeployApplyError(err, useGithubActionsOidc) {
+  if (!useGithubActionsOidc) return reportSdkError(err);
+  return reportSdkError(enhanceCiDeployError(err));
+}
+
+function enhanceCiDeployError(err) {
+  const existingBody = err?.body && typeof err.body === "object" && !Array.isArray(err.body)
+    ? err.body
+    : {};
+  const code = existingBody.code || err?.code || (err?.status === 402 ? "payment_required" : null);
+  const guidance = code ? CI_DEPLOY_ERROR_GUIDANCE[code] : null;
+  if (!guidance) return err;
+
+  const enhanced = Object.assign(new Error(err?.message || existingBody.message || String(code)), err);
+  enhanced.body = {
+    ...existingBody,
+    code,
+    message: existingBody.message || err?.message || "GitHub Actions OIDC deploy failed.",
+    hint: existingBody.hint || guidance.hint,
+    next_actions: Array.isArray(existingBody.next_actions) && existingBody.next_actions.length > 0
+      ? existingBody.next_actions
+      : guidance.next_actions,
+  };
+  return enhanced;
 }
 
 async function resumeCmd(args) {