@sentry/junior-github 0.69.0 → 0.71.0

package/SETUP.md

@@ -66,19 +66,22 @@ Repeat for `preview` and `development` as needed. After env changes, redeploy so
 
 ### Optional permission overrides
 
-By default, `installation-read` grants read the app installation's current permission envelope once per process and scopes read-capable permissions down to `read` when requesting a token. To declare the app permission envelope in the plugin and avoid that installation lookup, pass `appPermissions` when registering the plugin:
+By default, `installation-read` grants read the app installation's current permission envelope once per process and scopes read-capable permissions down to `read` when requesting a token. To declare the GitHub App permission envelope in the plugin and avoid that installation lookup, pass `appPermissions` when registering the plugin:
 
 ```ts
 githubPlugin({
   appPermissions: {
-    contents: "read",
+    actions: "write",
+    contents: "write",
     issues: "write",
+    metadata: "read",
     pull_requests: "write",
+    workflows: "write",
   },
 });
 ```
 
-Junior records these permissions as plugin capabilities. Installation-read token requests remain read-only by requesting read-capable configured permissions at `read` level and omitting GitHub permission fields that have no `read` value. GitHub remains the source of truth for whether a permission name or level exists.
+Junior records these permissions as plugin capabilities. The configured values are the maximum GitHub App envelope Junior may need for writes. Installation-read token requests remain read-only by requesting read-capable configured permissions at `read` level and omitting GitHub permission fields that have no `read` value. GitHub remains the source of truth for whether a permission name or level exists.
 
 GitHub App user-to-server tokens do not use OAuth scopes as their permission model. Their effective access is limited by the GitHub App's installed permissions, the app installation's repository access, and the requesting user's own GitHub access. GitHub returns an empty `scope` value for these tokens, so Junior cannot verify granted scopes from the token response.
 
@@ -95,7 +98,7 @@ Use `additionalUserScopes` only when an integration flow requires specific GitHu
 ## 3) Runtime behavior
 
 - When either GitHub skill is active, authenticated `gh` and `git` commands cause the runtime to inject GitHub credentials automatically for the current turn.
-- The plugin classifies GitHub traffic from the forwarded HTTP request. Safe app-readable API methods, GraphQL `GET`/`HEAD`/`OPTIONS` requests, and `git-upload-pack` use the `installation-read` grant. `GET /user` uses the `user-read` grant so account identity checks use the requester token. Write-specific REST URLs, non-read GraphQL methods, other non-read API methods, and `git-receive-pack` use the `user-write` grant.
+- The plugin classifies GitHub traffic from the forwarded HTTP request. Safe app-readable API methods, GraphQL `GET`/`HEAD`/`OPTIONS` requests, GraphQL `POST` bodies that prove the operation is a query, and `git-upload-pack` use the `installation-read` grant. `GET /user` uses the `user-read` grant so account identity checks use the requester token. Write-specific REST URLs, GraphQL mutations/subscriptions, unknown GraphQL `POST` bodies, other non-read API methods, and `git-receive-pack` use the `user-write` grant.
 - `user-read` and `user-write` require the requester, or an explicitly delegated user subject from an allowed system run, to authorize the GitHub App through the private OAuth flow. Missing or expired user authorization pauses interactive turns, sends a private authorization link, and resumes after approval.
 - Git commits use the requester as the commit author, Junior as committer, and a Junior `Co-Authored-By` trailer.
 - Issued credentials are reused only within the current turn, credential leases are cached separately by plugin grant name, and upstream 403 permission denials clear the cached lease before the next retry.

package/index.js

@@ -13,6 +13,7 @@ const GITHUB_AUTH_TOKEN_ENV = "GITHUB_TOKEN";
 const GITHUB_AUTH_TOKEN_PLACEHOLDER = "ghp_host_managed_credential";
 const MAX_LEASE_MS = 60 * 60 * 1000;
 const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+const GITHUB_GRAPHQL_RESPONSE_BODY_LIMIT_BYTES = 64 * 1024;
 const HTTP_READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
 const USER_TOKEN_GRANTS = new Set(["user-read", "user-write"]);
 const CONTENTS_WRITE_REQUIREMENTS = [
@@ -701,20 +702,133 @@ function githubUserReadReason(method, upstreamUrl) {
     : undefined;
 }
 
-function githubGraphqlAccess(method, upstreamUrl) {
+function parseGitHubGraphqlOperation(bodyText) {
+  if (typeof bodyText !== "string" || bodyText.trim().length === 0) {
+    return undefined;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyText);
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return undefined;
+  }
+  const query = parsed.query;
+  if (typeof query !== "string") {
+    return undefined;
+  }
+  const operationName =
+    typeof parsed.operationName === "string"
+      ? parsed.operationName.trim()
+      : undefined;
+  const normalized = maskGraphqlStringLiterals(
+    query.replace(/^\s*#[^\n\r]*(?:\r?\n|$)/gm, ""),
+  ).trim();
+  if (operationName) {
+    const namedOperation = normalized.match(
+      new RegExp(
+        `\\b(query|mutation|subscription)\\s+${escapeRegExp(operationName)}\\b`,
+      ),
+    )?.[1];
+    return namedOperation ? graphqlOperationAccess(namedOperation) : undefined;
+  }
+  const operation = normalized.match(/\b(query|mutation|subscription)\b/)?.[1];
+  const operationAccess = graphqlOperationAccess(operation);
+  if (operationAccess) {
+    return operationAccess;
+  }
+  if (normalized.startsWith("{")) {
+    return "read";
+  }
+  return undefined;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function graphqlOperationAccess(operation) {
+  if (operation === "mutation" || operation === "subscription") {
+    return "write";
+  }
+  if (operation === "query") {
+    return "read";
+  }
+  return undefined;
+}
+
+function maskGraphqlStringLiterals(query) {
+  return query.replace(/"""[\s\S]*?"""|"(?:\\.|[^"\\])*"/g, (match) =>
+    " ".repeat(match.length),
+  );
+}
+
+function githubGraphqlAccess(method, upstreamUrl, bodyText) {
   if (!isGitHubGraphqlUrl(upstreamUrl)) {
     return undefined;
   }
   if (HTTP_READ_METHODS.has(method)) {
     return "read";
   }
-  // GitHub GraphQL POST bodies can be read queries or write mutations. The
-  // egress hook intentionally does not read sandbox request bodies, so non-read
-  // methods require user-write attribution rather than risking an unattributed
-  // mutation through an installation-read token.
+  const operation = parseGitHubGraphqlOperation(bodyText);
+  if (operation) {
+    return operation;
+  }
+  // Unknown GraphQL POST bodies still require user-write attribution rather
+  // than risking an unattributed mutation through an installation-read token.
   return "write";
 }
 
+function githubGraphqlPermissionDeniedMessage(bodyText) {
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyText);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed) || !Array.isArray(parsed.errors)) {
+    return undefined;
+  }
+  for (const error of parsed.errors) {
+    if (!isRecord(error) || typeof error.message !== "string") {
+      continue;
+    }
+    const message = error.message;
+    if (
+      error.type === "NOT_FOUND" &&
+      /\bCould not resolve to a Repository with the name\b/.test(message)
+    ) {
+      return `GitHub GraphQL could not access the repository: ${message}`;
+    }
+    if (/\bResource not accessible by integration\b/.test(message)) {
+      return `GitHub GraphQL denied access: ${message}`;
+    }
+  }
+  return undefined;
+}
+
+function shouldInspectGitHubGraphqlResponse(ctx) {
+  if (
+    ctx.request.method.toUpperCase() !== "POST" ||
+    ctx.response.status !== 200
+  ) {
+    return false;
+  }
+  let upstreamUrl;
+  try {
+    upstreamUrl = new URL(ctx.request.url);
+  } catch {
+    return false;
+  }
+  if (!isGitHubGraphqlUrl(upstreamUrl)) {
+    return false;
+  }
+  const contentType = ctx.response.headers.get("content-type");
+  return contentType ? /\bjson\b/i.test(contentType) : false;
+}
+
 function githubApiWriteReason(method, upstreamUrl) {
   const pathname = upstreamUrl.pathname.toLowerCase();
   if (!isGitHubApiUrl(upstreamUrl)) {
@@ -830,7 +944,11 @@ async function githubGrantForEgress(ctx) {
     return grantForAccess("write", writeReason, "user-write");
   }
 
-  const graphqlAccess = githubGraphqlAccess(method, upstreamUrl);
+  const graphqlAccess = githubGraphqlAccess(
+    method,
+    upstreamUrl,
+    ctx.request.bodyText,
+  );
   if (graphqlAccess) {
     return grantForAccess(
       graphqlAccess,
@@ -969,6 +1087,21 @@ export function githubPlugin(options = {}) {
       grantForEgress(ctx) {
         return githubGrantForEgress(ctx);
       },
+      async onEgressResponse(ctx) {
+        if (!shouldInspectGitHubGraphqlResponse(ctx)) {
+          return;
+        }
+        const bodyText = await ctx.response.readText(
+          GITHUB_GRAPHQL_RESPONSE_BODY_LIMIT_BYTES,
+        );
+        if (!bodyText) {
+          return;
+        }
+        const message = githubGraphqlPermissionDeniedMessage(bodyText);
+        if (message) {
+          ctx.permissionDenied(message);
+        }
+      },
       async resolveOAuthAccount(ctx) {
         return await resolveUserAccount(ctx.tokens);
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-github",
-  "version": "0.69.0",
+  "version": "0.71.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -25,6 +25,6 @@
     "SETUP.md"
   ],
   "dependencies": {
-    "@sentry/junior-plugin-api": "0.69.0"
+    "@sentry/junior-plugin-api": "0.71.0"
   }
 }

package/skills/github-code/SKILL.md

@@ -130,15 +130,14 @@ Defaults:
 **Footers** (in order):
 
 1. Issue references (`Fixes #N`, `Refs SENTRY-N`), if any.
-2. `Action taken on behalf of Full Name.` — when on-behalf-of.
-3. Session link — when `gen_ai.conversation.id` is available:
+2. Session link — when `gen_ai.conversation.id` is available:
 
 ```
 ---
 [View Session in Sentry](https://sentry.sentry.io/traces/?project=4510944073809921&query=gen_ai.conversation.id%3A%22<url-encoded conversation id>%22)
 ```
 
-**Assignment:** resolve GitHub handles from evidence (`gh api search/users`, org membership, repo history) before assigning reviewers or the requester. Skip assignment when the handle cannot be confirmed.
+**Assignment:** resolve GitHub handles from evidence (`gh api search/users`, org membership, repo history) before assigning requested reviewers or assignees. Skip assignment when the handle cannot be confirmed.
 
 ### 7. Report result
 

package/skills/github-code/references/troubleshooting-workarounds.md

@@ -9,7 +9,8 @@ Use this table to recover quickly while keeping operations deterministic.
 | `Missing required option --repo`                                                | Repo not passed and no default was resolved.                                     | Resolve with `jr-rpc config get github.repo`; pass `--repo owner/repo` explicitly when missing.                                                                                      |
 | Command affects or authenticates against the wrong repo                         | Stale `github.repo` default or authenticated command missing explicit repo.      | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying.                                                                                         |
 | `GraphQL: Could not resolve to a Repository`                                    | Repo slug is wrong or inaccessible.                                              | Validate `owner/repo` and confirm app installation on target repository.                                                                                                             |
-| 401 Unauthorized                                                                | Host-managed GitHub App credentials were rejected.                               | Verify the target repo, then report the exact command failure and confirm the app installation and host environment variables.                                                       |
+| 401 Unauthorized                                                                | Issued GitHub credentials were rejected upstream.                                | Verify the target repo, then use the grant/auth signal to distinguish stale user OAuth from app installation or host env setup.                                                      |
+| `junior-auth-required provider=github grant=user-write`                         | User-to-server OAuth is missing or stale for a write request.                    | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually.                                                                                             |
 | `git push` fails with 401/403 or auth/permission output                         | Write permission is missing, app installation is too narrow, or remote is wrong. | Verify the remote and repo context, retry once, then confirm app permissions and installation scope if it still fails.                                                               |
 | Bash result includes `permission_denied` with `source: "upstream"`              | GitHub returned 403 after Junior injected the named grant.                       | Do not call this a Junior runtime block. Use the message, connected account, upstream target, grant requirements, accepted-permissions, and SSO fields to explain the GitHub denial. |
 | 403 Forbidden                                                                   | App lacks required permission on repo or install scope is too narrow.            | Verify the repo context, then confirm GitHub App permissions and installation scope.                                                                                                 |
@@ -22,7 +23,7 @@ Use this table to recover quickly while keeping operations deterministic.
 
 - Retry once for transient transport failures after verifying repo context.
 - Do not loop retries on repeated 401/403/404 validation errors.
-- Do not describe GitHub auth failures as user reconnect work; this plugin uses host-managed GitHub App credentials.
+- Treat missing or stale `user-read`/`user-write` grants as private GitHub App OAuth work; treat `installation-read` failures as app installation or host environment setup.
 - Do not describe `permission_denied` with `source: "upstream"` as Junior blocking the request. It means the egress proxy injected a credential, forwarded the request, and recorded GitHub's upstream 403. Prefer its `account` and `grant.requirements` fields over inference when explaining what to fix.
 - Do not infer permission level from OAuth scopes. GitHub App user tokens report no OAuth scopes; GitHub App permissions and accepted-permissions headers are the useful evidence.
 - For persistent permission problems, return explicit remediation and stop.

package/skills/github-issues/SKILL.md

@@ -59,11 +59,11 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
 - Compress source material. Research notes, hypotheses, or transcripts become a short summary + scoped bullets — never paste raw investigation into the body.
 - Do not add desired outcome, expected behavior, or acceptance criteria unless the thread explicitly requests them.
 - Preserve material source references inline.
-- When the request originated from a Slack thread or any on-behalf-of context, append a final line `Action taken on behalf of <name>.` using the action requester's real name. The action requester is the current `<requester>` or the person who explicitly asked you to create/update the issue, not necessarily the original reporter.
 
-**Attribution:**
+**Source attribution:**
 
-- Mention who raised the issue when clear from the thread. If the reporter differs from the action requester, keep them separate with durable body text such as `Reported by Alice.` or `Raised by Alice during incident triage.`
+- GitHub records the issue creator natively; do not add body or footer text to identify who asked Junior to create the issue.
+- If the person who originally reported or observed the problem differs from the issue creator, capture that with durable body text such as `Reported by Alice.` or `Raised by Alice during incident triage.`
 - Attach screenshots from the thread as image links when present.
 - Include code snippets, related issues, and related PRs only when they materially improve the issue.
 
@@ -72,7 +72,6 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
 Before running the `gh` create/edit command, check each gate. If any fails, revise and re-check before executing:
 
 - Title length ≤ 60 characters.
-- Delegated-action footer is the last line when applicable, using the action requester's real name, not the reporter's name unless they are the same person.
 - No session framing remains (channel refs, slash commands, @mentions, Slack thread IDs).
 - Body structure matches complexity — no empty sections, no restated title, no raw research dump.
 

package/skills/github-issues/references/issue-examples.md

@@ -45,8 +45,6 @@ Good structure — problem-specific sections:
 > ## Workaround
 >
 > Retry wrapper that catches LockError and clears the dedup key (PR #32).
->
-> Action taken on behalf of Jane Doe.
 
 ## Task example
 
@@ -66,28 +64,6 @@ Good scope — quantified and specific:
 > | `processReaction` | scheduling only                                   |
 > | `processAction`   | scheduling only                                   |
 > | `processMessage`  | scheduling + thread ID normalization + lock retry |
->
-> Action taken on behalf of Jane Doe.
-
-## Distinct reporter/requester example
-
-Bad attribution:
-
-> The bot resolved the review thread even though the warning still applies.
->
-> Action taken on behalf of Bojan Oro.
-
-Good attribution:
-
-> Warden can resolve its own review thread even when the underlying warning still appears valid and the PR remains blocked.
->
-> Reported by Bojan Oro.
->
-> - Observed on a PR where Warden left a review comment about a missing backport
-> - The review thread was later marked resolved by the bot
-> - The PR still showed a blocking warning
->
-> Action taken on behalf of David Cramer.
 
 ## Feature example
 
@@ -111,8 +87,6 @@ Good framing — current state, gap, options:
 > | --------------------------- | ---------------------------------- |
 > | File watch + hot reload     | Simple, but no atomicity guarantee |
 > | Config service with polling | Consistent, but adds a dependency  |
->
-> Action taken on behalf of Jane Doe.
 
 ## Principles
 
@@ -132,5 +106,3 @@ Good framing — current state, gap, options:
 - Speculative detail mixed into verified facts
 - Dumping a list of URLs without inline context
 - Session-specific content (slash commands, channel references, raw transcript framing, or unrelated user chatter)
-- Conflating reporter and action requester when they differ
-- Missing delegated attribution footer on user-requested issue creation

package/skills/github-issues/references/troubleshooting-workarounds.md

@@ -2,21 +2,22 @@
 
 Use this table to recover quickly while keeping operations deterministic.
 
-| Symptom                                                 | Likely cause                                                                | Fix                                                                                                                            |
-| ------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `unknown command "issue"` from `gh`                     | CLI version too old or wrong binary in the plugin runtime.                  | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available.     |
-| `Missing required option --repo`                        | Repo not passed and no default was resolved.                                | Resolve with `jr-rpc config get github.repo`; pass `--repo owner/repo` explicitly when missing.                                |
-| Command affects or authenticates against the wrong repo | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying.                                   |
-| `GraphQL: Could not resolve to a Repository`            | Repo slug is wrong or inaccessible.                                         | Validate `owner/repo` and confirm app installation on target repository.                                                       |
-| 401 Unauthorized                                        | Host-managed GitHub App credentials were rejected.                          | Verify the target repo, then report the exact command failure and confirm the app installation and host environment variables. |
-| 403 Forbidden                                           | App lacks required permission on repo or install scope is too narrow.       | Verify the repo context, then confirm GitHub App permissions and installation scope.                                           |
-| 404 Not Found                                           | Issue number or repo is wrong.                                              | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`.                                                        |
-| `gh issue edit` does not change labels                  | Wrong flag usage or wrong repo context.                                     | Use repeated `--add-label/--remove-label` flags and keep `--repo owner/repo` explicit.                                         |
-| Comment command fails with empty body                   | Body file missing/empty.                                                    | Ensure comment file exists and has content before `gh issue comment`.                                                          |
+| Symptom                                                 | Likely cause                                                                | Fix                                                                                                                             |
+| ------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `unknown command "issue"` from `gh`                     | CLI version too old or wrong binary in the plugin runtime.                  | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available.      |
+| `Missing required option --repo`                        | Repo not passed and no default was resolved.                                | Resolve with `jr-rpc config get github.repo`; pass `--repo owner/repo` explicitly when missing.                                 |
+| Command affects or authenticates against the wrong repo | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying.                                    |
+| `GraphQL: Could not resolve to a Repository`            | Repo slug is wrong or inaccessible.                                         | Validate `owner/repo` and confirm app installation on target repository.                                                        |
+| 401 Unauthorized                                        | Issued GitHub credentials were rejected upstream.                           | Verify the target repo, then use the grant/auth signal to distinguish stale user OAuth from app installation or host env setup. |
+| `junior-auth-required provider=github grant=user-write` | User-to-server OAuth is missing or stale for a write request.               | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually.                                        |
+| 403 Forbidden                                           | App lacks required permission on repo or install scope is too narrow.       | Verify the repo context, then confirm GitHub App permissions and installation scope.                                            |
+| 404 Not Found                                           | Issue number or repo is wrong.                                              | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`.                                                         |
+| `gh issue edit` does not change labels                  | Wrong flag usage or wrong repo context.                                     | Use repeated `--add-label/--remove-label` flags and keep `--repo owner/repo` explicit.                                          |
+| Comment command fails with empty body                   | Body file missing/empty.                                                    | Ensure comment file exists and has content before `gh issue comment`.                                                           |
 
 ## Retry guidance
 
 - Retry once for transient transport failures after verifying repo context.
 - Do not loop retries on repeated 401/403/404 validation errors.
-- Do not describe GitHub auth failures as user reconnect work; this plugin uses host-managed GitHub App credentials.
+- Treat missing or stale `user-read`/`user-write` grants as private GitHub App OAuth work; treat `installation-read` failures as app installation or host environment setup.
 - For persistent permission problems, return explicit remediation and stop.