base_url: "https://api.github.com",

    request_options: []

  ],

  github_oauth_scopes: ["repo", "read:org"],

  github_oauth_scopes: ["user:email"],

  voice_recording: [

    enabled: false,

    timeslice_ms: 5_000,

## Current contract

GitHub serves two distinct roles:

1. OAuth establishes the local OpenAgents account identity from GitHub's

   immutable numeric user ID.

2. A retained access token authorizes server-side GitHub repository tools with

   the user's delegated rights.

The application implements the second model only after the person chooses the

button labeled **Sign in and enable GitHub tools** beside a retention

disclosure. The callback stores the access token as versioned AES-256-GCM

ciphertext in the local user row. It does not discard the token after reading

the GitHub profile.

The OAuth app requests only `repo`. GitHub exposes public profile identity with

no OAuth scope, so the redundant `read:user` scope is not requested. The

repository tools need to read repositories the user authorizes, including

private repositories. GitHub OAuth Apps do not offer read-only source-code

access, so `repo` is the narrowest OAuth App scope that satisfies that feature

even though the scope grants broad read/write repository and related project

rights. The consent UI says so. OpenAgents exposes only its bounded read tools

to this credential. A future GitHub App migration should replace this broad scope with

fine-grained, repository-selected read permissions. See GitHub's

GitHub serves two distinct roles that use separate grants:

1. Sign-in establishes the local OpenAgents account identity from GitHub's

   immutable numeric user ID. It requests only `user:email`.

2. A future repository authorization flow will request the separate rights

   that server-side GitHub repository tools need.

The sign-in callback stores the email-scoped token as versioned AES-256-GCM

ciphertext in the local user row. It does not authorize repository imports,

organization membership checks, or other repository tools. Those operations

continue to require the exact `repo,read:org` scope set and fail closed until a

separate authorization flow supplies it.

GitHub exposes public profile identity without a scope. OpenAgents requests

`user:email` so sign-in can access the account's email address without asking

for repository access. A future GitHub App integration should use fine-grained,

repository-selected permissions for repository tools. See GitHub's

[OAuth scope reference](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)

and [authorization guidance](https://docs.github.com/en/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps).

## Implemented flow

1. `POST /auth/github?github_tools=enabled` refuses a request that does not

   carry the explicit tools choice, then creates a high-entropy state value, a PKCE S256

1. `POST /auth/github` creates a high-entropy state value, a PKCE S256

   challenge, and a short-lived PostgreSQL OAuth-attempt row.

2. The encrypted browser session carries only the attempt reference and PKCE

   verifier while GitHub handles authorization.

3. `GET /auth/github/callback` consumes the attempt exactly once, exchanges the

   code server-side, refuses missing or different granted scopes, and reads the

   code server-side, refuses any grant other than `user:email`, and reads the

   GitHub `/user` projection server-side.

4. `OpenAgents.Accounts` upserts the local account by numeric GitHub ID and

   refreshes the mutable login, name, and avatar projection.

   envelope carrying the non-secret active key ID before the ciphertext is

   stored. The row also records scopes and connection/rotation timestamps.

6. The authenticated session contains only the local user ID. Repository tools

   unseal the token server-side when an explicit GitHub operation needs it.

   reject the sign-in token because it does not contain their required scopes.

7. `DELETE /logout` clears the browser session but intentionally does not

   revoke the retained GitHub grant.

8. `DELETE /github/connection` authenticates the browser and uses the OAuth

environment host. Tests use deterministic local configuration and fake Req

responses; they do not require a live GitHub credential.

Rows migrated from the pre-Gate-6 envelope retain `read:user,repo` metadata

because that is the grant they actually received. Before staging admission,

revoke those legacy grants and have their owners reconnect under `repo` only;

do not rewrite metadata to claim a provider-side scope reduction that did not

occur.

Existing rows retain their recorded scope metadata because that is the grant

they actually received. Do not rewrite metadata to claim a provider-side scope

reduction that did not occur.

## Rotation and data rights

| Database | `OPENAGENTS_MIGRATE_ON_BOOT` | `true` in staging and production |

| GitHub | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | OAuth application credentials for the selected environment |

| GitHub | `GITHUB_REDIRECT_URI` | Exact HTTPS callback on `PHX_HOST` |

| GitHub | `GITHUB_OAUTH_SCOPES` | Exactly `repo,read:org`; repository import needs retained repository access and organization creation needs membership access |

| GitHub | `GITHUB_OAUTH_SCOPES` | Exactly `user:email`; sign-in does not request repository access |

| GitHub | `OPENAGENTS_ADMIN_GITHUB_IDS` | Comma-separated immutable numeric GitHub IDs allowed to use operator surfaces; never use logins |

| GitHub | `GITHUB_TOKEN_ENCRYPTION_KEY` | Base64-encoded 32-byte key for the selected environment |

| GitHub | `GITHUB_TOKEN_ENCRYPTION_KEY_ID` | Bounded active-key identifier prefixed with `development-`, `test-`, `staging-`, or `production-` to match the runtime |

    do: Application.fetch_env!(:openagents, :github_oauth_scopes)

  defp valid_scopes?(scopes) do

    scopes == configured_github_scopes()

    scopes in [configured_github_scopes(), OpenAgents.GitHubOAuth.required_scopes()]

  end

end

  @default_attempt_ttl_seconds 600

  @github_api_version "2022-11-28"

  @user_agent "OpenAgents"

  @required_scopes ["repo", "read:org"]

  @requested_scopes ["user:email"]

  @repository_scopes ["repo", "read:org"]

  @type attempt :: %{required(String.t()) => String.t() | integer()}

  def revoke(_access_token), do: {:error, :invalid_token}

  @doc "The exact OAuth scopes retained with each connected GitHub grant."

  @doc "The exact OAuth scopes requested during GitHub sign-in."

  @spec requested_scopes() :: [String.t()]

  def requested_scopes, do: @required_scopes

  def requested_scopes, do: @requested_scopes

  @doc "The only OAuth scopes admitted by the GitHub-backed namespace and import model."

  @doc "The OAuth scopes required by the GitHub-backed namespace and import model."

  @spec required_scopes() :: [String.t()]

  def required_scopes, do: @required_scopes

  def required_scopes, do: @repository_scopes

  defp exchange_code(config, code, verifier) do

    request_options =

  end

  defp validate_scope_configuration do

    if Application.get_env(:openagents, :github_oauth_scopes) == @required_scopes,

    if Application.get_env(:openagents, :github_oauth_scopes) == @requested_scopes,

      do: :ok,

      else: {:error, :github_oauth_scope_configuration_invalid}

  end

         :ok <- validate_redirect(redirect_uri, environment),

         :ok <-

           ensure(

             scopes == ["repo", "read:org"],

             scopes == ["user:email"],

             :github_oauth_scopes,

             "must include repository and organization membership access"

             "must contain only user email access"

           ),

         :ok <-

           ensure(

  attr :size, :atom, values: [:default, :xs, :sm, :lg], default: :default

  attr :action, :string,

    default: "/auth/github?github_tools=enabled",

    default: "/auth/github",

    doc: "where the sign-in posts; the caller owns the route"

  attr :class, :any, default: nil

  @attempt_session_key "github_oauth_attempt"

  @identity_session_key "posthog_identity"

  def start(conn, %{"github_tools" => "enabled"}) do

  def start(conn, _params) do

    case GitHubOAuth.begin_authorization() do

      {:ok, attempt, authorization_url} ->

        Analytics.capture("auth_started", Analytics.browser_distinct_id(conn))

    end

  end

  def start(conn, _params), do: auth_failure(conn, "consent_required")

  def callback(conn, %{"code" => code, "state" => state}) do

    attempt = get_session(conn, @attempt_session_key)

    verifier = if is_map(attempt), do: attempt["verifier"]

  @classes [

    :public_read,

    :public_action,

    :authenticated_browser,

    :authenticated_api,

    :operator,

         )

  defp policy(%{path: "/auth/github", verb: :post}),

    do: declaration(:authenticated_browser, "explicit OAuth applicant", "identity:connect", true)

    do: declaration(:public_action, "OAuth applicant", "identity:sign-in", true)

  defp policy(%{path: "/auth/github/callback"}),

    do: declaration(:authenticated_browser, "one-time OAuth attempt", "identity:connect", true)

export DATABASE_URL="ecto://sarah_app:${DB_PASSWORD}@127.0.0.1:5432/sarah"

export DNS_CLUSTER_QUERY="sarah.fleet.internal"

export GITHUB_OAUTH_SCOPES="repo,read:org"

export GITHUB_OAUTH_SCOPES="user:email"

export GITHUB_REDIRECT_URI="https://openagents.com/auth/github/callback"

export GITHUB_TOKEN_DECRYPTION_KEYS_JSON="{}"

export GITHUB_TOKEN_ENCRYPTION_KEY_ID="production-legacy-v1"

: "${OPENAI_API_KEY:?OPENAI_API_KEY is required}"

: "${SECRET_KEY_BASE:?SECRET_KEY_BASE is required}"

export GITHUB_OAUTH_SCOPES="repo,read:org"

export GITHUB_OAUTH_SCOPES="user:email"

export GITHUB_REDIRECT_URI="https://staging.openagents.com/auth/github/callback"

# Written as an explicit default rather than ${VAR:-{}}: POSIX expansion ends

# at the first `}`, so a preset value came back corrupted with a trailing

# Changelog

## Coder 0.1

## Coder v0.1.0

Released August 2026.

Released August 26, 2026.

Coder 0.1 brings interactive coding, model access, tools, delegation, and

Coder v0.1.0 brings interactive coding, model access, tools, delegation, and

durable session history into the OpenAgents CLI.

### Work in your terminal

    assert {:ok, user} = Accounts.upsert_github_user(profile(501, "token-owner"))

    assert {:error, :invalid_token_scopes} =

             Accounts.store_github_token(user, "gho_too_broad", ["read:user", "repo"])

             Accounts.store_github_token(user, "gho_too_broad", ["user:email", "repo"])

    assert {:ok, connected} = Accounts.store_github_token(user, "gho_retained")

    assert connected.github_token_key_id == "test-2026-08"

             end)

    assert disconnected.id == user.id

    assert {:ok, repository_user} =

             Accounts.upsert_github_user(profile(502, "repository-token-owner"))

    assert {:ok, _repository_grant} =

             Accounts.store_github_token(repository_user, "gho_repository", ["repo", "read:org"])

    assert disconnected.github_token_ciphertext == nil

    assert disconnected.github_token_scopes == []

    assert {:error, :github_token_missing} = Accounts.github_token(disconnected)

  setup do

    original_scopes = Application.fetch_env!(:openagents, :github_oauth_scopes)

    Application.put_env(:openagents, :github_oauth_scopes, ["repo", "read:org"])

    Application.put_env(:openagents, :github_oauth_scopes, ["user:email"])

    on_exit(fn ->

      Application.put_env(:openagents, :github_oauth_scopes, original_scopes)

    assert query["client_id"] == "test-github-client-id"

    assert query["redirect_uri"] == "http://127.0.0.1:4002/auth/github/callback"

    assert query["scope"] == "repo read:org"

    assert query["scope"] == "user:email"

    assert query["state"] == attempt["state"]

    assert query["code_challenge_method"] == "S256"

    assert byte_size(query["code_challenge"]) == 43

      Req.Test.json(conn, %{

        "access_token" => "short-lived-token",

        "token_type" => "bearer",

        "scope" => "read:org,repo"

        "scope" => "user:email"

      })

    end)

    verifier = Base.url_encode64(:crypto.strong_rand_bytes(32), padding: false)

    assert {:ok, profile, access_token, ["repo", "read:org"]} =

    assert {:ok, profile, access_token, ["user:email"]} =

             GitHubOAuth.exchange_and_fetch("github-code", verifier)

    assert access_token == "short-lived-token"

      Req.Test.expect(__MODULE__, fn conn ->

        Req.Test.json(conn, %{

          "access_token" => "short-lived-token",

          "scope" => "repo read:org"

          "scope" => "user:email"

        })

      end)

    Req.Test.expect(__MODULE__, fn conn ->

      Req.Test.json(conn, %{

        "access_token" => "provider-token",

        "scope" => "repo,read:org"

        "scope" => "user:email"

      })

    end)

  end

  test "a missing or broadened granted scope fails before profile lookup" do

    for scope <- [nil, "", "repo", "read:org", "read:user", "repo,read:org,admin:org"] do

    for scope <- [nil, "", "repo", "read:org", "read:user", "user:email,repo"] do

      setup_req_test()

      Req.Test.expect(__MODULE__, fn conn ->

    end

  end

  test "the retained grant model requires exactly repository and organization read scopes" do

  test "sign-in scope stays separate from repository authorization scopes" do

    assert GitHubOAuth.required_scopes() == ["repo", "read:org"]

    assert GitHubOAuth.requested_scopes() == ["repo", "read:org"]

    assert GitHubOAuth.requested_scopes() == ["user:email"]

  end

  defp setup_req_test do

    refute encoded =~ "ecto://"

  end

  test "GitHub sign-in accepts only the email scope" do

    assert {:error, %{setting: :github_oauth_scopes}} =

             staging_settings()

             |> Map.put(:github_oauth_scopes, ["repo", "read:org"])

             |> RuntimeConfig.validate()

    assert {:ok, _config} = RuntimeConfig.validate(staging_settings())

  end

  test "staging gates refuse features before their admission gate" do

    settings = staging_settings() |> put_nested(:voice, :enabled, true)

    refute user.github_token_ciphertext =~ "ephemeral-github-token"

    assert {:ok, "ephemeral-github-token"} = Accounts.github_token(user)

    assert user.github_token_key_id == "test-2026-08"

    assert user.github_token_scopes == ["repo", "read:org"]

    assert user.github_token_scopes == ["user:email"]

    assert user.github_token_connected_at

    cookie = authenticated |> get_resp_header("set-cookie") |> Enum.join(";")

    assert get_session(callback, "user_id") == nil

  end

  test "GitHub tools require an explicit retained-token choice", %{conn: conn} do

    refused =

  test "GitHub sign-in does not require repository-tool consent", %{conn: conn} do

    started =

      conn

      |> init_test_session(%{})

      |> put_req_header("x-csrf-token", Plug.CSRFProtection.get_csrf_token())

      |> post(~p"/auth/github")

    assert redirected_to(refused) == ~p"/?auth_error=consent_required"

    assert get_session(refused, "github_oauth_attempt") == nil

    assert redirected_to(started) =~ "https://github.com/login/oauth/authorize?"

    assert get_session(started, "github_oauth_attempt")

  end

  test "disconnect revokes the GitHub grant and clears local token metadata", %{conn: conn} do

    conn

    |> init_test_session(%{})

    |> put_req_header("x-csrf-token", csrf_token)

    |> post(~p"/auth/github?github_tools=enabled")

    |> post(~p"/auth/github")

  end

  defp attempt_and_state(conn) do

    Req.Test.expect(__MODULE__, fn conn ->

      Req.Test.json(conn, %{

        "access_token" => "ephemeral-github-token",

        "scope" => "repo,read:org"

        "scope" => "user:email"

      })

    end)

  refuse: a redirect to the public root, or `401` for the session-authenticated

  API routes that answer a client rather than a browser.

  The two GitHub OAuth entries are in this class and refuse the same way. They

  are where a person authenticates, so an anonymous request reaches them, but

  it leaves with an `auth_error` and no session rather than with a page.

  The GitHub callback is in this class and refuses an anonymous request that

  does not carry a valid one-time OAuth attempt. The sign-in action is the

  bounded public action that creates that attempt, so it is classified

  separately.

  The websocket at `/live` is classified in the same class and is not

  dispatchable here; `OpenAgentsWeb.UserAuth.on_mount/4` gates it and

             "credential_exported" => false,

             "product_data_deletion" => "retained_until_explicit_disconnect",

             "rotated_at" => nil,

             "scopes" => ["repo", "read:org"]

             "scopes" => ["user:email"]

           }

    refute inspect(export) =~ "gho_export_sentinel"

defmodule OpenAgentsWeb.RepositoryImportControllerTest do

  use OpenAgentsWeb.ConnCase, async: false

  alias OpenAgents.{Accounts, ApiTokens, Repo}

  alias OpenAgents.{Accounts, ApiTokens, GitHubOAuth, Repo}

  setup {Req.Test, :verify_on_exit!}

  test "POST /api/v1/user/repos/imports accepts one frozen GitHub snapshot", %{conn: conn} do

    user = github_user("repository-import-api", "octavia")

    assert {:ok, user} = Accounts.store_github_token(user, "gho_import_fixture")

    assert {:ok, user} = store_repository_grant(user, "gho_import_fixture")

    main_sha = String.duplicate("a", 40)

    tag_sha = String.duplicate("b", 40)

  test "an import inherits the GitHub repository visibility when omitted", %{conn: conn} do

    user = github_user("repository-public-import-api", "octavia")

    assert {:ok, user} = Accounts.store_github_token(user, "gho_public_import_fixture")

    assert {:ok, user} = store_repository_grant(user, "gho_public_import_fixture")

    main_sha = String.duplicate("c", 40)

    expect_import_source(user, main_sha, nil, false)

  test "organization creation requires an active GitHub administrator membership", %{conn: conn} do

    user = github_user("repository-org-api")

    assert {:ok, user} = Accounts.store_github_token(user, "gho_org_fixture")

    assert {:ok, user} = store_repository_grant(user, "gho_org_fixture")

    Req.Test.expect(__MODULE__, fn github_conn ->

      assert github_conn.request_path == "/user/memberships/orgs"

      conn: conn

    } do

      user = github_user("repository-foreign-import", "octavia")

      assert {:ok, user} = Accounts.store_github_token(user, "gho_foreign_fixture")

      assert {:ok, user} = store_repository_grant(user, "gho_foreign_fixture")

      expect_foreign_source(String.duplicate("d", 40), false, "MIT")

      conn: conn

    } do

      user = github_user("repository-mirror-api", "octavia")

      assert {:ok, user} = Accounts.store_github_token(user, "gho_mirror_fixture")

      assert {:ok, user} = store_repository_grant(user, "gho_mirror_fixture")

      main_sha = String.duplicate("e", 40)

      expect_foreign_source(main_sha, false, "MIT")

    test "an upstream with no license records the absence rather than omitting it", %{conn: conn} do

      user = github_user("repository-unlicensed-mirror", "octavia")

      assert {:ok, user} = Accounts.store_github_token(user, "gho_unlicensed_fixture")

      assert {:ok, user} = store_repository_grant(user, "gho_unlicensed_fixture")

      expect_foreign_source(String.duplicate("f", 40), false, nil)

    test "a private source cannot be mirrored", %{conn: conn} do

      user = github_user("repository-private-mirror", "octavia")

      assert {:ok, user} = Accounts.store_github_token(user, "gho_private_mirror_fixture")

      assert {:ok, user} = store_repository_grant(user, "gho_private_mirror_fixture")

      expect_foreign_source(String.duplicate("1", 40), true, "MIT")

    end

  end

  defp store_repository_grant(user, token) do

    Accounts.store_github_token(user, token, GitHubOAuth.required_scopes())

  end

  defp expect_foreign_source(main_sha, private?, license) do

    Req.Test.expect(__MODULE__, fn github_conn ->

      assert github_conn.request_path == "/repos/tobi/walgit"

      landing

      |> recycle()

      |> put_req_header("x-csrf-token", Plug.CSRFProtection.get_csrf_token())

      |> post(~p"/auth/github?github_tools=enabled")

      |> post(~p"/auth/github")

    state = oauth_state(started)

    expect_github(4_129, "device-return-person")

      conn

      |> init_test_session(%{})

      |> put_req_header("x-csrf-token", Plug.CSRFProtection.get_csrf_token())

      |> post(~p"/auth/github?github_tools=enabled")

      |> post(~p"/auth/github")

    state = oauth_state(started)

    expect_github(4_130, "ordinary-sign-in-person")

        bounced

        |> recycle()

        |> put_req_header("x-csrf-token", Plug.CSRFProtection.get_csrf_token())

        |> post(~p"/auth/github?github_tools=enabled")

        |> post(~p"/auth/github")

      state = oauth_state(started)

      expect_github(4_131, "crafted-code-person")

    Req.Test.expect(__MODULE__, fn conn ->

      Req.Test.json(conn, %{

        "access_token" => "ephemeral-github-token",

        "scope" => "repo,read:org"

        "scope" => "user:email"

      })

    end)

    # current product identity.

    assert html =~ "Introducing"

    assert html =~ "Your all-in-one coding agent."

    assert html =~ ~s(action="/auth/github?github_tools=enabled")

    assert html =~ ~s(action="/auth/github")

    assert html =~ "Log in with GitHub"

    # The scope disclosure was removed from the hero at the owner's direction.

    assert redirected_to(conn, 302) == ~p"/docs/changelog"

  end

  test "the documentation changelog presents Coder 0.1", %{conn: conn} do

  test "the documentation changelog presents Coder v0.1.0 with its release date", %{conn: conn} do

    {:ok, _view, html} = live(conn, ~p"/docs/changelog")

    assert html =~ "Coder 0.1"

    assert html =~ "Coder v0.1.0"

    assert html =~ "Released August 26, 2026."

    assert html =~ "Choose how inference runs"

    assert html =~ "Delegate work"

  end

  test "one-time import picker creates an immutable GitHub import receipt", %{conn: conn} do

    user = github_user("repository-live-import", "import-owner")

    assert {:ok, user} = Accounts.store_github_token(user, "gho_live_import")

    assert {:ok, user} =

             Accounts.store_github_token(

               user,

               "gho_live_import",

               OpenAgents.GitHubOAuth.required_scopes()

             )

    main_sha = String.duplicate("a", 40)

    Req.Test.stub(__MODULE__, &github_import_response(&1, user, main_sha))

  test "one-time import picker defaults to the GitHub repository visibility", %{conn: conn} do

    user = github_user("repository-live-public-import", "import-owner")

    assert {:ok, user} = Accounts.store_github_token(user, "gho_live_public_import")

    assert {:ok, user} =

             Accounts.store_github_token(

               user,

               "gho_live_public_import",

               OpenAgents.GitHubOAuth.required_scopes()

             )

    main_sha = String.duplicate("c", 40)

    Req.Test.stub(__MODULE__, fn github_conn ->

    end)

  end

  test "GitHub sign-in is the bounded public identity action" do

    route = route!(:post, "/auth/github")

    assert route.class == :public_action

    assert route.principal == "OAuth applicant"

    assert route.scope == "identity:sign-in"

    assert route.mutation

  end

  test "public forge reads and bearer-authenticated forge writes are separate" do

    read = route!(:get, "/api/v1/repos/:owner/:repo/issues")

    write = route!(:post, "/api/v1/repos/:owner/:repo/issues")