Remove "scope" functionality from OAuth APIs

[gr2m]

Remove "scope" functionality from OAuth APIs

[gr2m]

@imwiss when creating an OAuth token for a GitHub App, the response still includes a "scopes" key, I wonder if that should be removed?

For reference, here is a request to exchange an OAuth code for an access token using credentials from https://github.com/apps/gr2m

POST https://github.com/login/oauth/access_token {
  headers: { accept: 'application/json' },
  client_id: 'Iv1.2340495690bca085', 
  client_secret: '[REDACTED]',
  code: '[REDACTED]',
  state: 'y6sczn4thd'
}

{
  "status": 200,
  "url": "https://github.com/login/oauth/access_token",
  "headers": {
    "cache-control": "max-age=0, private, must-revalidate",
    "connection": "close",
    "content-encoding": "gzip",
    "content-security-policy": "default-src 'none'; base-uri 'self'; block-all-mixed-content; connect-src 'self' uploads.github.com www.githubstatus.com collector.githubapp.com api.github.com github-cloud.s3.amazonaws.com github-production-repository-file-5c1aeb.s3.amazonaws.com github-production-upload-manifest-file-7fdce7.s3.amazonaws.com github-production-user-asset-6210df.s3.amazonaws.com cdn.optimizely.com logx.optimizely.com/v1/events wss://alive.github.com; font-src github.githubassets.com; form-action 'self' github.com gist.github.com; frame-ancestors 'none'; frame-src render.githubusercontent.com; img-src 'self' data: github.githubassets.com identicons.github.com collector.githubapp.com github-cloud.s3.amazonaws.com user-images.githubusercontent.com/ *.githubusercontent.com; manifest-src 'self'; media-src 'none'; script-src github.githubassets.com; style-src 'unsafe-inline' github.githubassets.com; worker-src github.com/socket-worker-5029ae85.js gist.github.com/socket-worker-5029ae85.js",
    "content-type": "application/json; charset=utf-8",
    "date": "Thu, 18 Feb 2021 23:43:55 GMT",
    "etag": "W/\"2d17546dddd13e7f7d8146fd32d75b8d\"",
    "expect-ct": "max-age=2592000, report-uri=\"https://api.github.com/_private/browser/errors\"",
    "referrer-policy": "origin-when-cross-origin, strict-origin-when-cross-origin",
    "server": "GitHub.com",
    "strict-transport-security": "max-age=31536000; includeSubdomains; preload",
    "transfer-encoding": "chunked",
    "vary": "X-PJAX, Accept-Encoding, Accept, X-Requested-With",
    "x-content-type-options": "nosniff",
    "x-frame-options": "deny",
    "x-github-request-id": "FC92:91A5:11A397:14374C:602EFBBB",
    "x-xss-protection": "1; mode=block"
  },
  "data": {
    "access_token": "121222ac8b1e8054feb903117deddda7f3beb6d9",
    "token_type": "bearer",
    "scope": ""
  }
}

Instead of a "scopes" key, it would be great to have a "permissions' key instead, similar to the "permissions" in the response of POST /app/installations/{installation_id}/access_tokens

Example

{
  // ...
  "permissions": {
    "issues": "write",
    "contents": "read"
  }
}

Three questions you could help me figuring out

1. Is there currently any way to retrieve the permission for a token? Scopes are returned in the `"X-OAuth-Scopes" header, but as far as I know there is counterpart for permissions.
2. What happens to OAuth tokens if a GitHub App changes its permissions? Does the token retain the previous permissions for each installation even after the user accepts the permission changes? Does it inherit the permissions for each installation even if changes occurred after the token was created? Does it get invalidated altogether? I tried to test it with the https://github.com/apps/gr2m app but I didn't get an email about the permission changes and I don't know where to grant the newly requested changes, nothing shows up on the installation page (https://github.com/settings/installations/14816926)
3. Can I request fewer permission and access to fewer installations/repositories when requesting an OAuth token? Say my app is installed on 3 organizations and has read/write access for both issues and pull requests, but I'd like to create an OAuth token that only has access to a specific repository with read access to issues only, is that possible today?

[gr2m]

1. Is there currently any way to retrieve the permission for a token? Scopes are returned in the `"X-OAuth-Scopes" header, but as far as I know there is counterpart for permissions.

I figured this one out: https://docs.github.com/en/developers/apps/identifying-and-authorizing-users-for-github-apps#check-which-installations-resources-a-user-can-access

GET /user/installations includes a { "permissions": {} } key for each installation the user has access

[gr2m]

done via #255