Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions convex/_generated/api.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ import type * as apiKeys_query from "../apiKeys/query.js";
import type * as apiKeys_security from "../apiKeys/security.js";
import type * as auth from "../auth.js";
import type * as crons from "../crons.js";
import type * as github_accessVerification from "../github/accessVerification.js";
import type * as github_accessVerificationResult from "../github/accessVerificationResult.js";
import type * as github_action from "../github/action.js";
import type * as github_botIdentity from "../github/botIdentity.js";
import type * as github_helpers from "../github/helpers.js";
Expand Down Expand Up @@ -234,6 +236,8 @@ declare const fullApi: ApiFromModules<{
"apiKeys/security": typeof apiKeys_security;
auth: typeof auth;
crons: typeof crons;
"github/accessVerification": typeof github_accessVerification;
"github/accessVerificationResult": typeof github_accessVerificationResult;
"github/action": typeof github_action;
"github/botIdentity": typeof github_botIdentity;
"github/helpers": typeof github_helpers;
Expand Down
246 changes: 246 additions & 0 deletions convex/github/accessVerification.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,246 @@
import { httpAction } from "../_generated/server";
import { internal } from "../_generated/api";
import {
fetchAccessibleGitHubInstallationIds,
GITHUB_INSTALLATION_ATTESTATION_REQUEST_TIMEOUT_MS,
githubApiHeaders,
} from "./oauthInstallationAttestation";
import {
ACCESS_VERIFICATION_RESULT_PARAM,
type AccessVerificationResult,
} from "./accessVerificationResult";

/**
* "Verify GitHub access": a GitHub App user authorization, separate from
* sign-in, that records which installations the signed-in user can reach.
* The user token lives only for the callback request and is revoked after.
*/
export const ACCESS_VERIFICATION_CALLBACK_PATH = "/github/access/callback";
export const ACCESS_VERIFICATION_TTL_MS = 10 * 60 * 1_000;
const DEFAULT_RETURN_PATH = "/repositories/connect";

/**
* Where GitHub sends the user back: the same site as sign-in's OAuth
* callback, so one GitHub App lists both under one host.
*/
export function accessVerificationRedirectUri(): string | null {
const site =
process.env.CUSTOM_AUTH_SITE_URL || process.env.CONVEX_SITE_URL || null;
return site && `${site}${ACCESS_VERIFICATION_CALLBACK_PATH}`;
}

function base64Url(bytes: Uint8Array): string {
return btoa(String.fromCharCode(...bytes))
.replace(/\+/g, "-")
.replace(/\//g, "_")
.replace(/=+$/, "");
}

async function sha256(value: string): Promise<Uint8Array> {
return new Uint8Array(
await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value)),
);
}

/** A random secret for the OAuth state or the PKCE verifier. */
export function generateSecret(): string {
return base64Url(crypto.getRandomValues(new Uint8Array(32)));
}

export async function hashState(state: string): Promise<string> {
return Array.from(await sha256(state), (byte) =>
byte.toString(16).padStart(2, "0"),
).join("");
}

/** A path on Gitdog's site to return to; anything else is refused. */
export function readReturnPath(value: string): string | null {
if (!value.startsWith("/") || value.includes("\\")) return null;
const base = "https://gitdog.invalid";
try {
const url = new URL(value, base);
// Check the normalized path: "/..//evil.example" becomes "//evil.example",
// which a browser reads as another host.
if (url.origin !== base || url.pathname.startsWith("//")) return null;
return `${url.pathname}${url.search}`;
} catch {
return null;
}
}

export async function buildAuthorizeUrl(args: {
clientId: string;
redirectUri: string;
state: string;
codeVerifier: string;
}): Promise<string> {
const url = new URL("https://github.com/login/oauth/authorize");
url.searchParams.set("client_id", args.clientId);
url.searchParams.set("redirect_uri", args.redirectUri);
url.searchParams.set("state", args.state);
url.searchParams.set(
"code_challenge",
base64Url(await sha256(args.codeVerifier)),
);
url.searchParams.set("code_challenge_method", "S256");
url.searchParams.set("allow_signup", "false");
return url.toString();
}

async function requestJson(
url: string,
init: RequestInit,
): Promise<Record<string, unknown>> {
const response = await fetch(url, {
...init,
signal: AbortSignal.timeout(
GITHUB_INSTALLATION_ATTESTATION_REQUEST_TIMEOUT_MS,
),
});
if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
const payload = (await response.json()) as unknown;
if (payload === null || typeof payload !== "object" || Array.isArray(payload))
throw new Error("GitHub returned an invalid response");
return payload as Record<string, unknown>;
}

async function exchangeCode(args: {
code: string;
codeVerifier: string;
clientId: string;
clientSecret: string;
redirectUri: string;
}): Promise<string> {
const payload = await requestJson(
"https://github.com/login/oauth/access_token",
{
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({
client_id: args.clientId,
client_secret: args.clientSecret,
code: args.code,
code_verifier: args.codeVerifier,
redirect_uri: args.redirectUri,
}),
},
);
const token = payload.access_token;
if (typeof token !== "string" || token === "")
throw new Error("GitHub did not grant user authorization");
return token;
}

async function fetchGitHubAccountId(token: string): Promise<string> {
const user = await requestJson("https://api.github.com/user", {
headers: githubApiHeaders(`Bearer ${token}`),
});
if (typeof user.id !== "number" || !Number.isSafeInteger(user.id))
throw new Error("GitHub returned an invalid user");
return user.id.toString();
}

/** Best effort: the token is never stored, and GitHub expires it anyway. */
async function revokeToken(args: {
token: string;
clientId: string;
clientSecret: string;
}): Promise<void> {
try {
await fetch(`https://api.github.com/applications/${args.clientId}/token`, {
method: "DELETE",
headers: githubApiHeaders(
`Basic ${btoa(`${args.clientId}:${args.clientSecret}`)}`,
),
body: JSON.stringify({ access_token: args.token }),
signal: AbortSignal.timeout(
GITHUB_INSTALLATION_ATTESTATION_REQUEST_TIMEOUT_MS,
),
});
} catch {
// The token expires on GitHub's side regardless.
}
}

function returnTo(
siteUrl: string,
returnPath: string,
result: AccessVerificationResult,
): Response {
let url = new URL(returnPath, siteUrl);
// Never leave Gitdog's site, whatever the stored path says.
if (url.origin !== new URL(siteUrl).origin)
url = new URL(DEFAULT_RETURN_PATH, siteUrl);
url.searchParams.set(ACCESS_VERIFICATION_RESULT_PARAM, result);
return new Response(null, {
status: 302,
headers: { Location: url.toString(), "Cache-Control": "no-store" },
});
}

export const accessVerificationCallback = httpAction(async (ctx, request) => {
const siteUrl = process.env.SITE_URL;
const clientId = process.env.GITHUB_APP_CLIENT_ID;
const clientSecret = process.env.GITHUB_APP_CLIENT_SECRET;
const redirectUri = accessVerificationRedirectUri();
if (!siteUrl || !clientId || !clientSecret || !redirectUri)
return new Response("GitHub access verification is not configured", {
status: 503,
});

const params = new URL(request.url).searchParams;
const state = params.get("state");
if (!state) return returnTo(siteUrl, DEFAULT_RETURN_PATH, "failed");
const pending = await ctx.runMutation(
internal.github.internalMutation.consumeAccessVerification,
{ stateHash: await hashState(state), now: Date.now() },
);
if (!pending) return returnTo(siteUrl, DEFAULT_RETURN_PATH, "failed");
if (pending.expired) return returnTo(siteUrl, pending.returnPath, "failed");

const code = params.get("code");
if (!code) {
// Only the user declining is a cancellation; GitHub reports setup
// problems such as a redirect_uri mismatch the same way.
const declined = params.get("error") === "access_denied";
if (!declined)
console.error("GitHub access verification error:", params.get("error"));
return returnTo(
siteUrl,
pending.returnPath,
declined ? "cancelled" : "failed",
);
}

let token: string | null = null;
try {
token = await exchangeCode({
code,
codeVerifier: pending.codeVerifier,
clientId,
clientSecret,
redirectUri,
});
const [githubAccountId, installationIds] = await Promise.all([
fetchGitHubAccountId(token),
fetchAccessibleGitHubInstallationIds(token),
]);
const result = await ctx.runMutation(
internal.github.internalMutation.saveVerifiedInstallationAccess,
{ userId: pending.userId, githubAccountId, installationIds },
);
return returnTo(siteUrl, pending.returnPath, result);
} catch (error) {
// Messages never include the token.
console.error(
"GitHub access verification failed:",
error instanceof Error ? error.message : "unknown error",
);
return returnTo(siteUrl, pending.returnPath, "failed");
} finally {
if (token) await revokeToken({ token, clientId, clientSecret });
}
});
14 changes: 14 additions & 0 deletions convex/github/accessVerificationResult.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
// Shared with the web app, so this module imports nothing.

/** The query parameter the return page reads to show how verification ended. */
export const ACCESS_VERIFICATION_RESULT_PARAM = "githubAccess";

/** The outcomes other than success, each with its own message. */
export const ACCESS_VERIFICATION_PROBLEMS = [
"account_mismatch",
"cancelled",
"failed",
] as const;

export type AccessVerificationResult =
"verified" | (typeof ACCESS_VERIFICATION_PROBLEMS)[number];
50 changes: 50 additions & 0 deletions convex/github/action.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,14 @@ import {
} from "./repositoryIdentity";
import { INSTALLATION_WEBHOOK_STATE_MAX_RETRY_COUNT } from "./webhookAccessStateAttestation";
import { REPOSITORY_ACCESS_RECONCILIATION_MAX_RETRY_COUNT } from "./repositoryAccessReconciliation";
import {
ACCESS_VERIFICATION_TTL_MS,
accessVerificationRedirectUri,
buildAuthorizeUrl,
generateSecret,
hashState,
readReturnPath,
} from "./accessVerification";

const RECONCILIATION_PAGE_SIZE = 50;
const RECONCILIATION_STALE_AFTER_MS = 10 * 60 * 1_000;
Expand Down Expand Up @@ -1324,3 +1332,45 @@ export const recoverOAuthInstallation = action({
}
},
});

/**
* Start "Verify GitHub access": returns the GitHub authorization URL that
* records which installations the signed-in user can reach, then returns to
* `returnPath` on Gitdog's site.
*/
export const startAccessVerification = action({
args: { returnPath: v.string() },
returns: v.object({ url: v.string() }),
handler: async (ctx, args) => {
const userId = await getAuthUserId(ctx);
if (!userId) throw new Error("Not authenticated");
const returnPath = readReturnPath(args.returnPath);
if (returnPath === null) throw new Error("Invalid return path");
const clientId = process.env.GITHUB_APP_CLIENT_ID;
const redirectUri = accessVerificationRedirectUri();
if (!clientId || !redirectUri)
throw new Error("GitHub access verification is not configured");

const state = generateSecret();
const codeVerifier = generateSecret();
await ctx.runMutation(
internal.github.internalMutation.createAccessVerification,
{
userId,
stateHash: await hashState(state),
codeVerifier,
returnPath,
now: Date.now(),
ttlMs: ACCESS_VERIFICATION_TTL_MS,
},
);
return {
url: await buildAuthorizeUrl({
clientId,
redirectUri,
state,
codeVerifier,
}),
};
},
});
Loading