wip v28

Author: geraldarthurdavis

BITCODE_V28_QA.md

@@ -336,6 +336,12 @@ Automated verification after this implementation pass:
 - May 11 externality-readiness check validates the provided GitHub App identity without writing secrets to source: the private key parses, GitHub API returns App ID `244206`, app slug `engi-software-agents`, and the supplied client ID matches the app record. The app can list installations and create an installation token for at least one installation. Initial check found it was not installed on `engineeredsoftware/ENGI`.
 - May 12 externality-readiness recheck confirms the GitHub App is now installed on `engineeredsoftware/ENGI`: `GET /repos/engineeredsoftware/ENGI/installation` returns 200, installation token creation returns 201, `engineeredsoftware/ENGI` is readable, default branch is `main`, and `BITCODE_SPEC.txt` is readable through the app installation token. GitHub App externality is ready for V28 Terminal Give/Need QA against ENGI.
 - May 12 Supabase readiness resolves project reachability and key acceptance but remains blocked on database schema. The project URL is reachable, auth settings return 200 with the supplied publishable key, and the secret key is accepted by the Supabase API gateway. Core Bitcode tables including `user_profiles`, `user_connections`, `vcs_repositories`, `btd_asset_pack_ranges`, and `btd_mint_receipts` return `PGRST205` table-not-found responses, so migrations have not been applied to this testnet project yet. Source now accepts both the older `NEXT_PUBLIC_SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY` names and the newer `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` / `SUPABASE_SECRET_KEY` names so the provided testnet variables can be used directly after migration.
+- May 12 GitHub App setup/callback hardening: the active install link is now `https://github.com/apps/bitcode-github-app-auxillary` in Auxillaries and docs-facing surfaces. The retained public callback route `/github/callback` redirects to `/tps/github/callback`, and the retained setup route `/github/setup` redirects to `/tps/github/app-install`, preserving query fields. The callback handler collects GitHub App installation fields including `installation_id`, `setup_action`, `state`, `target_id`, and `target_type`; when a Supabase user session exists it exchanges the installation for an installation token and stores the GitHub connection as installation-scoped metadata without exposing tokens in client connection status. The GitHub App description copy for the registration form is: `Connect GitHub repositories to Bitcode so Terminal can measure Needs, synthesize BTD-backed AssetPacks, and return proof-bound delivery status.`
+- Recommended GitHub App URLs for production registration: homepage `https://bitcode.exchange`, callback URL `https://bitcode.exchange/github/callback`, setup URL `https://bitcode.exchange/github/setup`, public app link `https://github.com/apps/bitcode-github-app-auxillary`. For local callback QA, add a temporary allowed callback/setup pair for the active local port or use the deployed staging domain; GitHub App setup redirects do not inherit the browser's local origin automatically.
+- `pnpm -C uapi exec jest --runInBand tests/api/vcsRoutes.test.ts tests/api/vcsGithubCallbackRoute.test.ts tests/auxillariesConnectsPane.test.tsx tests/publicDocsPageContent.test.tsx`: 11 passed after GitHub App install-link and callback/setup handling.
+- `pnpm -C uapi exec jest --runInBand --testMatch '**/tests/userConnectionsGithubRoute.test.ts'`: 6 passed after GitHub connection-status token redaction.
+- `pnpm -C uapi exec tsc --noEmit --pretty false`: pass after GitHub App callback/setup and public install-link wiring.
+- `pnpm -C uapi run build`: pass after GitHub App callback/setup and public install-link wiring.
 - `pnpm -C uapi exec tsc --noEmit --pretty false`: pass after the formal protocol package split.
 - `pnpm -C uapi run test:e2e:commercial-mvp`: 50 passed after Conversations streaming, Conversations exit, and Terminal transaction-search stabilization.
 - `npm --prefix protocol-demonstration run test:integration`: 58 passed after standalone demonstration/package-boundary cleanup.
@@ -406,9 +412,11 @@ NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<testnet Supabase publishable key> \
 SUPABASE_SECRET_KEY=<testnet Supabase secret key> \
 GITHUB_APP_CLIENT_ID=<GitHub App client ID> \
 GITHUB_APP_CLIENT_SECRET=<GitHub App client secret> \
+GITHUB_APP_REDIRECT_URI=http://127.0.0.1:3001/github/callback \
 GITHUB_APP_ID=<GitHub App ID> \
 GITHUB_PRIVATE_KEY="$(cat /Users/garrettmaring/Downloads/engi-software-agents.2026-05-11.private-key.pem)" \
 GITHUB_WEBHOOK_SECRET=<GitHub webhook secret> \
+NEXT_PUBLIC_GITHUB_APP_PUBLIC_URL=https://github.com/apps/bitcode-github-app-auxillary \
 NEXT_PUBLIC_MASTER_MOCK_MODE=false \
 NEXT_PUBLIC_ENABLE_MOCKS=false \
 NEXT_PUBLIC_MOCK_USER_AUXILLARIES=false \

packages/vcs/src/__tests__/vcs-config.test.ts

@@ -20,6 +20,9 @@ describe('@bitcode/vcs configuration helpers', () => {
     delete process.env.GITHUB_CLIENT_ID;
     delete process.env.GITHUB_CLIENT_SECRET;
     delete process.env.GITHUB_REDIRECT_URI;
+    delete process.env.GITHUB_APP_CLIENT_ID;
+    delete process.env.GITHUB_APP_CLIENT_SECRET;
+    delete process.env.GITHUB_APP_REDIRECT_URI;
     delete process.env.GITHUB_APP_ID;
     delete process.env.GITHUB_PRIVATE_KEY;
     delete process.env.GITHUB_WEBHOOK_SECRET;
@@ -34,6 +37,18 @@ describe('@bitcode/vcs configuration helpers', () => {
     expect((cfg as any).privateKey).toBe('private-key');
   });
 
+  it('prefers GitHub App OAuth client aliases when present', () => {
+    process.env.GITHUB_APP_CLIENT_ID = 'app-client';
+    process.env.GITHUB_APP_CLIENT_SECRET = 'app-secret';
+    process.env.GITHUB_APP_REDIRECT_URI = 'https://app.test/github/callback';
+
+    const cfg = getVCSConfig('github');
+
+    expect(cfg.clientId).toBe('app-client');
+    expect(cfg.clientSecret).toBe('app-secret');
+    expect(cfg.redirectUri).toBe('https://app.test/github/callback');
+  });
+
   it('returns provider-specific OAuth scopes', () => {
     expect(getProviderScopes('github')).toContain('repo');
     expect(getProviderScopes('gitlab')).toContain('read_repository');

uapi/app/(root)/components/MarketingScreenshotSection.tsx

@@ -31,6 +31,7 @@ import type { Screenshot } from './marketing-types';
 // Reuse the global neon underline + glow styles defined for Bitcode headers.
 import "@/styles/bitcode-header-shiny-text.css";
 import { motion, useInView } from "framer-motion";
+import { BITCODE_GITHUB_APP_PUBLIC_URL } from '@/lib/github-app-url';
 
 // Persist a module-level flag so the animation only ever plays once per page
 // load, even if the component gets unmounted/remounted (e.g. via Next.js
@@ -795,7 +796,7 @@ const MarketingScreenshotSection: React.FC = () => {
                 <a
                   ref={linkRef}
                   id="esi-link"
-                  href="https://github.com/marketplace/bitcode-github-app"
+                  href={BITCODE_GITHUB_APP_PUBLIC_URL}
                   target="_blank"
                   rel="noopener noreferrer"
                   className="glowing-underline text-slate-100 hover:text-white transition-colors font-semibold"

uapi/app/api/auxillaries/connections/github/route.ts

@@ -27,6 +27,21 @@ function resolveInstallationId(connectionData: Record<string, unknown> | null |
   return Number.isFinite(numeric) ? numeric : null;
 }
 
+const sensitiveConnectionDataKeys = new Set([
+  'access_token',
+  'oauth_token',
+  'refresh_token',
+  'token',
+  'client_secret',
+  'private_key',
+]);
+
+function sanitizeConnectionData(connectionData: Record<string, unknown>) {
+  return Object.fromEntries(
+    Object.entries(connectionData).filter(([key]) => !sensitiveConnectionDataKeys.has(key.toLowerCase())),
+  );
+}
+
 export async function GET(_request: Request) {
   const { supabase, user } = await requireUser();
   if (!user) {
@@ -49,7 +64,7 @@ export async function GET(_request: Request) {
   if (!installationId) {
     return NextResponse.json({
       success: true,
-      connectionData,
+      connectionData: sanitizeConnectionData(connectionData),
       repositories: [],
       organizations: [],
     });
@@ -69,7 +84,7 @@ export async function GET(_request: Request) {
 
     return NextResponse.json({
       success: true,
-      connectionData,
+      connectionData: sanitizeConnectionData(connectionData),
       repositories,
       organizations,
     });

uapi/app/api/vcs/[provider]/callback/route.ts

@@ -0,0 +1,11 @@
+import { createRouteWrapper } from '@bitcode/middleware';
+
+import { handleGitHubCallback } from '@/app/tps/github/_callback-handler';
+
+import type { ProviderRouteContext } from '../../_shared';
+
+export const runtime = 'nodejs';
+
+export const GET = createRouteWrapper(async (request: Request, context: ProviderRouteContext) =>
+  handleGitHubCallback(request, context),
+);

uapi/app/api/vcs/[provider]/setup/route.ts

@@ -0,0 +1,3 @@
+export const runtime = 'nodejs';
+
+export { GET } from '../callback/route';

uapi/app/docs/DocsArticlePage.tsx

@@ -3,6 +3,7 @@ import Link from 'next/link';
 
 import TerminalWorkspaceCard from '@/app/terminal/TerminalWorkspaceCard';
 import Footer from '@/components/base/bitcode/layout/footer';
+import { BITCODE_GITHUB_APP_PUBLIC_URL } from '@/lib/github-app-url';
 
 import {
   BITCODE_DOCS_CHAPTERS,
@@ -518,6 +519,16 @@ export default function DocsArticlePage({ page }: DocsArticlePageProps) {
               >
                 Docs hub
               </Link>
+              {page.slug === 'auxillaries' || page.slug === 'commercial-interfaces' ? (
+                <a
+                  href={BITCODE_GITHUB_APP_PUBLIC_URL}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex rounded-full border border-cyan-300/22 bg-cyan-400/10 px-4 py-2 text-[11px] font-semibold uppercase tracking-[0.18em] text-cyan-50 transition hover:border-cyan-300/42 hover:bg-cyan-400/16"
+                >
+                  Install GitHub App
+                </a>
+              ) : null}
             </div>
           </section>
 

uapi/app/github/callback/route.ts

@@ -0,0 +1,12 @@
+export const runtime = 'nodejs';
+
+export function GET(request: Request) {
+  const redirectUrl = new URL('/tps/github/callback', request.url);
+  redirectUrl.search = new URL(request.url).search;
+  return new Response(null, {
+    status: 308,
+    headers: {
+      Location: redirectUrl.toString(),
+    },
+  });
+}

uapi/app/github/setup/route.ts

@@ -0,0 +1,12 @@
+export const runtime = 'nodejs';
+
+export function GET(request: Request) {
+  const redirectUrl = new URL('/tps/github/app-install', request.url);
+  redirectUrl.search = new URL(request.url).search;
+  return new Response(null, {
+    status: 308,
+    headers: {
+      Location: redirectUrl.toString(),
+    },
+  });
+}

uapi/app/tps/README.md

@@ -8,8 +8,10 @@
 Examples
 - `/tps/supabase/callback` – Auth OTP/OAuth callback overlay
 - `/tps/wallet/connect` – Wallet connection or settlement overlay
-- `/tps/github/app-install` – GitHub App installation/verification overlay
+- `/tps/github/callback` – GitHub App user-authorization callback handler
+- `/tps/github/app-install` – GitHub App installation/setup handler
 - `/tps/twilio/sms/[runId]` – SMS run viewer
 
 Transition policy
 - Retained callback pages (`/login/callback`, `/github/callback`, `/sms/view/[runId]`) permanently redirect (308) to the new `/tps/...` routes.
+- Retained GitHub setup pages (`/github/setup`) permanently redirect (308) to `/tps/github/app-install` and preserve `installation_id`, `setup_action`, `state`, `target_id`, and `target_type`.