Merge pull request #47 from engineeredsoftware/v31/gate-4-connects-provider-readiness

V31 Gate 4: Connects Provider Readiness

Author: geraldarthurdavis

.github/workflows/bitcode-gate-quality.yml

@@ -98,6 +98,7 @@ jobs:
             node scripts/check-v31-gate1-spec-roadmap-opening.mjs --skip-branch-check
             node scripts/check-v31-gate2-auxillaries-package-route-contracts.mjs --skip-branch-check
             node scripts/check-v31-gate3-profile-account-state.mjs --skip-branch-check
+            node scripts/check-v31-gate4-connects-provider-readiness.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -138,6 +139,9 @@ jobs:
         run: |
           pnpm --dir uapi exec jest --runTestsByPath \
             tests/userDataRoute.test.ts \
+            tests/api/auxillariesGithubConnectionRoute.test.ts \
+            tests/api/vcsRoutes.test.ts \
+            tests/auxillariesExternalsPane.test.tsx \
             tests/profileStep.test.tsx \
             tests/api/readReviewRoute.test.ts \
             tests/api/pipelineHarnessRoute.test.ts \

BITCODE_SPEC_V31.md

@@ -243,6 +243,9 @@ Gate 4 Connects precision:
 - Provider readiness records name provider id, installation/account state, token presence class, scopes class, last readback status, blocker, and repair action.
 - Secrets and raw provider tokens are never stored in telemetry, UI metadata, or proof hooks.
 - Recovery attempts produce before/after readiness roots and never silently downgrade provider policy.
+- `AuxillariesConnectionReadiness` is the canonical provider-readiness object for Connects and VCS routes. It carries `providerId`, `providerName`, `credentialPosture`, `tokenPresenceClass`, `scopesClass`, `lastReadbackStatus`, `blocker`, `repairAction`, source-safe metadata, and `providerReadinessRoot`.
+- Provider connection routes may store or validate private provider credentials at the route boundary, but responses, telemetry, proof hooks, and UI metadata can only expose classified token/scope/readback posture and source-safe account labels.
+- `AuxillariesRecoveryRun` records provider recovery as before-readiness root, after-readiness root, repair action, execution id, outcome, and source-safety class; it never serializes the provider credential that made the repair possible.
 
 Gate 5 Wallet/BTD precision:
 

BITCODE_SPEC_V31_DELTA.md

@@ -127,6 +127,13 @@ Closure acceptance:
 - GitHub and provider connection routes emit source-safe readiness/recovery evidence;
 - recovery runs record before/after readiness roots and never leak tokens.
 
+Gate 4 implementation centers:
+
+- `AuxillariesConnectionReadiness` now names provider id/name, token presence class, scopes class, readback state, blocker, repair action, source-safe metadata, and `providerReadinessRoot`.
+- VCS connection and GitHub Auxillaries routes emit `providerReadiness` and source-safe `recoveryRun` evidence while keeping access tokens out of responses.
+- The Externals pane consumes `connectionReadiness` and `recoveryRuns` from `/api/auxillaries/data`, rendering classified provider posture and compact proof roots without local readiness rederivation.
+- Focused package, route, and pane tests prove classified provider readiness, before/after recovery roots, UI projection, and response redaction.
+
 ### Gate 5: Wallet And BTD Pane Readiness
 
 Gate 5 connects Wallet and BTD panes to V30 wallet/BTD primitives.

BITCODE_SPEC_V31_NOTES.md

@@ -87,3 +87,10 @@ Gate 3 is closed only when Profile/account state is not just a form payload.
 It must be a package-owned support state that binds account identity, profile completeness issues, repair routes, wallet binding posture, model/template preference posture, notification posture, data-sharing posture, and proof roots.
 The Profile pane may present and link repairs, but it must consume the package contract and must not locally rederive account readiness or completeness law.
 Route hydration must include template preference and notification readback where available, while missing storage rows degrade into explicit repair posture rather than generic missing data.
+
+## Gate 4 closure note
+
+Gate 4 is closed only when Connects provider state is a source-safe readiness contract rather than a raw OAuth/VCS status blob.
+Provider readiness must name provider id/name, installation state, credential posture, token presence class, scopes class, last readback status, blocker, repair action, and proof root without exposing raw provider credentials.
+VCS and GitHub Auxillaries routes may use credentials internally to validate or repair a connection, but responses, UI metadata, telemetry, and recovery proof hooks must carry only classified posture and before/after readiness roots.
+The Externals pane can display compact provider proof detail, but it must consume `connectionReadiness` and `recoveryRuns` from the package-owned Auxillaries contract instead of locally deciding provider law.

BITCODE_SPEC_V31_PARITY_MATRIX.md

@@ -113,9 +113,9 @@ No `_legacy/` source is active source truth.
 
 | Requirement | Source evidence | Current V31 judgment |
 | --- | --- | --- |
-| Provider readiness is source-safe | provider connection contracts and tests | pending |
-| Recovery runs record before/after readiness roots | recovery route and execution tests | pending |
-| Tokens and credentials never enter telemetry/UI metadata | source-safety tests and scans | pending |
+| Provider readiness is source-safe | `AuxillariesConnectionReadiness` in `packages/api/src/routes/auxillaries-contract.ts` carries provider id/name, token presence class, scopes class, last readback, blocker, repair action, source-safe metadata, and `providerReadinessRoot` | drafted |
+| Recovery runs record before/after readiness roots | `uapi/app/api/vcs/[provider]/connection/route.ts`, `uapi/app/api/auxillaries/connections/github/route.ts`, and `uapi/tests/api/auxillariesGithubConnectionRoute.test.ts` emit and test before/after readiness roots | drafted |
+| Tokens and credentials never enter telemetry/UI metadata | `packages/api/src/routes/__tests__/auxillaries-contract.test.ts`, `uapi/tests/api/vcsRoutes.test.ts`, `uapi/tests/api/auxillariesGithubConnectionRoute.test.ts`, and `uapi/tests/auxillariesExternalsPane.test.tsx` cover response/UI redaction and source-safe projection | drafted |
 
 ## Gate 5 Parity
 

SPECIFICATIONS_ROADMAP.md

@@ -5,7 +5,7 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V30`
 - Current active canon: `BITCODE_SPEC_V30.md`
 - Current draft target: `BITCODE_SPEC_V31.md`
-- Current working gate: V31 Gate 3 Profile and account state, which deepens the package-owned Auxillaries Profile contract with account identity, wallet binding posture, model/template preferences, notifications, data-sharing posture, explicit blockers, and repair routes over the V30 Protocol/BTD substrate.
+- Current working gate: V31 Gate 4 Connects provider readiness and recovery, which deepens source-safe provider connection posture with provider id/name, installation state, token presence class, scopes class, last readback status, blocker, repair action, readiness roots, and before/after recovery evidence over the V30 Protocol/BTD substrate.
 - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work.
 
 This roadmap is not an active system specification.

package.json

@@ -67,6 +67,7 @@
     "check:v31-gate1": "node scripts/check-v31-gate1-spec-roadmap-opening.mjs",
     "check:v31-gate2": "node scripts/check-v31-gate2-auxillaries-package-route-contracts.mjs",
     "check:v31-gate3": "node scripts/check-v31-gate3-profile-account-state.mjs",
+    "check:v31-gate4": "node scripts/check-v31-gate4-connects-provider-readiness.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",

packages/api/README.md

@@ -34,6 +34,13 @@ proof roots. Profile UI and routes can display or persist explicit fields, but
 they should not recalculate readiness locally; missing profile/account facts
 must degrade into named blockers or repairable issues.
 
+Connects provider readiness is also package-owned. `AuxillariesConnectionReadiness`
+classifies provider id/name, installation state, credential posture, token
+presence, scopes, last readback, blocker, repair action, source-safe metadata,
+and a readiness root. Routes may validate credentials privately, but API
+responses, UI metadata, telemetry, and recovery proof hooks must only serialize
+classified readiness and `AuxillariesRecoveryRun` before/after roots.
+
 In V26 fourth-gate this package is where merged-world Bitcode becomes concrete:
 - `/conversations` continuity
 - `/executions` compatibility and pipeline-run APIs

packages/api/src/routes/__tests__/auxillaries-contract.test.ts

@@ -54,6 +54,10 @@ describe('Auxillaries package route contracts', () => {
         valid: true,
         provider: 'github',
         username: 'bitcode',
+        scopes: ['repo', 'contents:write'],
+        tokenPresenceClass: 'present_source_safe',
+        lastReadbackStatus: 'succeeded',
+        lastReadbackAt: '2026-05-21T02:00:00.000Z',
         metadata: {
           token: 'provider-token',
         },
@@ -130,10 +134,17 @@ describe('Auxillaries package route contracts', () => {
       enabledRepositoryCount: 1,
     });
     expect(payload.connectionReadiness[0]).toMatchObject({
+      providerId: 'github',
+      providerName: 'GitHub',
       provider: 'github',
       connected: true,
       valid: true,
       credentialPosture: 'present_source_safe',
+      tokenPresenceClass: 'present_source_safe',
+      scopesClass: 'repo_read_write',
+      lastReadbackStatus: 'succeeded',
+      blocker: null,
+      repairAction: 'none',
     });
     expect(payload.walletBtdPaneState.signerPosture).toMatchObject({
       ready: true,
@@ -152,6 +163,7 @@ describe('Auxillaries package route contracts', () => {
     expect(JSON.stringify(payload)).not.toContain('wallet-secret');
     expect(JSON.stringify(payload)).not.toContain('repository source');
     expect(JSON.stringify(payload)).not.toContain('private prompt body');
+    expect(JSON.stringify(payload.connectionReadiness[0].metadata)).not.toContain('provider-token');
     expect(assertAuxillariesJsonSafe(payload)).toBeUndefined();
   });
 
@@ -175,6 +187,12 @@ describe('Auxillaries package route contracts', () => {
     const blockerIds = payload.readinessDiagnostics.map((diagnostic) => diagnostic.blockerId);
     expect(payload.profileState.accountReadiness).toBe('blocked');
     expect(payload.connectionReadiness[0].requiredRepairAction).toBe('connect_provider');
+    expect(payload.connectionReadiness[0]).toMatchObject({
+      tokenPresenceClass: 'missing',
+      scopesClass: 'missing',
+      lastReadbackStatus: 'not_attempted',
+      blocker: 'connects.github.connect_provider',
+    });
     expect(payload.walletBtdPaneState.signerPosture.requiredAction).toBe('connect_wallet');
     expect(blockerIds).toEqual(expect.arrayContaining([
       'profile.missing',
@@ -233,6 +251,8 @@ describe('Auxillaries package route contracts', () => {
 
     expect(parseAuxillariesContractSnapshot(snapshot).recoveryRuns[0].recoveryRoot)
       .toMatch(/^[0-9a-f]{64}$/);
+    expect(JSON.stringify(snapshot.recoveryRuns)).not.toContain('access_token');
+    expect(JSON.stringify(snapshot.recoveryRuns)).not.toContain('oauth_token');
     expect(validateAuxillariesContractSnapshot({ kind: 'wrong' })).toMatchObject({
       valid: false,
     });

packages/api/src/routes/auxillaries-contract.ts

@@ -17,6 +17,14 @@ export type AuxillariesRetryPolicy = 'manual_retry' | 'after_repair' | 'not_retr
 export type AuxillariesProfileRepairSeverity = 'blocking' | 'recoverable';
 export type AuxillariesNotificationState = 'ready' | 'attention_needed' | 'contact_missing' | 'unknown';
 export type AuxillariesDataSharingState = 'configured' | 'limited' | 'not_configured' | 'unknown';
+export type AuxillariesProviderTokenPresenceClass = 'present_source_safe' | 'missing' | 'invalid' | 'unknown';
+export type AuxillariesProviderScopesClass =
+  | 'repo_read_write'
+  | 'repo_read_only'
+  | 'metadata_only'
+  | 'missing'
+  | 'unknown';
+export type AuxillariesProviderReadbackStatus = 'succeeded' | 'failed' | 'not_attempted' | 'unknown';
 
 const CANONICAL_AUXILLARY_PANES = new Set<string>(AUXILLARY_FLOW_STEPS);
 const AUXILLARY_PANE_ALIASES: Record<string, ConcreteAuxillaryPane> = {
@@ -174,6 +182,8 @@ export interface AuxillariesProfileState {
 
 export interface AuxillariesConnectionReadiness {
   kind: 'AuxillariesConnectionReadiness';
+  providerId: string;
+  providerName: string;
   provider: string;
   connected: boolean;
   valid: boolean;
@@ -184,11 +194,21 @@ export interface AuxillariesConnectionReadiness {
     | 'missing'
     | 'invalid'
     | 'unknown';
+  tokenPresenceClass: AuxillariesProviderTokenPresenceClass;
+  scopesClass: AuxillariesProviderScopesClass;
+  lastReadbackStatus: AuxillariesProviderReadbackStatus;
+  lastReadbackAt: string | null;
+  blocker: string | null;
   requiredRepairAction:
     | 'none'
     | 'connect_provider'
     | 'reauthorize_provider'
     | 'repair_provider_inventory';
+  repairAction:
+    | 'none'
+    | 'connect_provider'
+    | 'reauthorize_provider'
+    | 'repair_provider_inventory';
   sourceSafetyClass: AuxillariesSourceSafetyClass;
   metadata: Record<string, unknown>;
   providerReadinessRoot: string;
@@ -894,9 +914,18 @@ export function buildAuxillariesConnectionReadiness(input: {
 }): AuxillariesConnectionReadiness {
   const connection = asRecord(toAuxillariesJsonSafe(input.connection ?? null));
   const status = asRecord(toAuxillariesJsonSafe(input.connectionStatus ?? null));
+  const statusMetadata = asRecord(status?.metadata);
+  const connectionMetadata = asRecord(connection?.metadata);
   const connected = readBoolean(status?.connected) ?? Boolean(connection);
   const valid = readBoolean(status?.valid) ?? connected;
   const provider = readString(status?.provider) ?? readString(connection?.provider) ?? input.provider;
+  const providerId = readString(status?.providerId) ??
+    readString(status?.provider_id) ??
+    readString(connection?.provider_id) ??
+    provider;
+  const providerName = readString(status?.providerName) ??
+    readString(status?.provider_name) ??
+    readProviderName(provider);
   const accountLabel =
     readString(status?.username) ??
     readString(connection?.login) ??
@@ -916,20 +945,77 @@ export function buildAuxillariesConnectionReadiness(input: {
       : repositories.length === 0
         ? 'repair_provider_inventory'
         : 'none';
+  const tokenPresenceClass = readProviderTokenPresenceClass(
+    readString(status?.tokenPresenceClass) ??
+    readString(status?.token_presence_class) ??
+    readString(statusMetadata?.tokenPresenceClass) ??
+    readString(statusMetadata?.token_presence_class),
+  ) ?? (!connected
+    ? 'missing'
+    : !valid
+      ? 'invalid'
+      : hasProviderTokenEvidence(status) || hasProviderTokenEvidence(connection)
+        ? 'present_source_safe'
+        : 'unknown');
+  const scopes = [
+    ...readStringList(status?.scopes),
+    ...readStringList(status?.scope),
+    ...readStringList(statusMetadata?.scopes),
+    ...readStringList(statusMetadata?.scope),
+    ...readStringList(connection?.scopes),
+    ...readStringList(connection?.scope),
+    ...readStringList(connectionMetadata?.scopes),
+    ...readStringList(connectionMetadata?.scope),
+  ];
+  const scopesClass = readProviderScopesClass(
+    readString(status?.scopesClass) ??
+    readString(status?.scopes_class) ??
+    readString(statusMetadata?.scopesClass) ??
+    readString(statusMetadata?.scopes_class),
+  ) ?? deriveProviderScopesClass({ connected, scopes });
+  const lastReadbackStatus = readProviderReadbackStatus(
+    readString(status?.lastReadbackStatus) ??
+    readString(status?.last_readback_status) ??
+    readString(status?.readbackStatus) ??
+    readString(status?.readback_status) ??
+    readString(statusMetadata?.lastReadbackStatus) ??
+    readString(statusMetadata?.last_readback_status) ??
+    readString(statusMetadata?.readbackStatus) ??
+    readString(statusMetadata?.readback_status),
+  ) ?? (!connected ? 'not_attempted' : valid ? 'succeeded' : 'failed');
+  const lastReadbackAt = readString(status?.lastReadbackAt) ??
+    readString(status?.last_readback_at) ??
+    readString(statusMetadata?.lastReadbackAt) ??
+    readString(statusMetadata?.last_readback_at) ??
+    null;
+  const blocker = readString(status?.blocker) ??
+    readString(statusMetadata?.blocker) ??
+    (requiredRepairAction === 'none' ? null : `connects.${provider}.${requiredRepairAction}`);
+  const repairAction = requiredRepairAction;
   const withoutRoot = {
     kind: 'AuxillariesConnectionReadiness' as const,
+    providerId,
+    providerName,
     provider,
     connected,
     valid,
     accountLabel,
     installationState: connected ? 'installed' as const : 'missing' as const,
     credentialPosture,
+    tokenPresenceClass,
+    scopesClass,
+    lastReadbackStatus,
+    lastReadbackAt,
+    blocker,
     requiredRepairAction,
+    repairAction,
     sourceSafetyClass: 'secret_free_summary' as AuxillariesSourceSafetyClass,
     metadata: {
       repositories: repositories.length,
+      repositoryCount: repositories.length,
       instanceUrl: readString(status?.instanceUrl),
       expiresAt: readString(status?.expiresAt),
+      scopes,
     },
   };
 
@@ -1461,6 +1547,92 @@ function readDataSharingState(value: string | null): AuxillariesDataSharingState
   return null;
 }
 
+function readProviderName(provider: string) {
+  if (provider === 'github') return 'GitHub';
+  if (provider === 'gitlab') return 'GitLab';
+  if (provider === 'bitbucket') return 'Bitbucket';
+  return provider;
+}
+
+function readProviderTokenPresenceClass(value: string | null): AuxillariesProviderTokenPresenceClass | null {
+  if (
+    value === 'present_source_safe' ||
+    value === 'missing' ||
+    value === 'invalid' ||
+    value === 'unknown'
+  ) {
+    return value;
+  }
+  return null;
+}
+
+function readProviderScopesClass(value: string | null): AuxillariesProviderScopesClass | null {
+  if (
+    value === 'repo_read_write' ||
+    value === 'repo_read_only' ||
+    value === 'metadata_only' ||
+    value === 'missing' ||
+    value === 'unknown'
+  ) {
+    return value;
+  }
+  return null;
+}
+
+function readProviderReadbackStatus(value: string | null): AuxillariesProviderReadbackStatus | null {
+  if (
+    value === 'succeeded' ||
+    value === 'failed' ||
+    value === 'not_attempted' ||
+    value === 'unknown'
+  ) {
+    return value;
+  }
+  return null;
+}
+
+function readStringList(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => (typeof entry === 'string' ? entry.trim() : ''))
+      .filter(Boolean);
+  }
+  if (typeof value === 'string') {
+    return value
+      .split(/[,\s]+/u)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+function hasProviderTokenEvidence(value: UnknownRecord | null) {
+  if (!value) return false;
+  return [
+    value.token_present,
+    value.tokenPresent,
+    value.access_token,
+    value.oauth_token,
+    value.refresh_token,
+    value.token,
+  ].some((entry) => readBoolean(entry) === true || readString(entry) === REDACTED_VALUE);
+}
+
+function deriveProviderScopesClass(input: {
+  connected: boolean;
+  scopes: string[];
+}): AuxillariesProviderScopesClass {
+  if (!input.connected) return 'missing';
+  if (input.scopes.length === 0) return 'unknown';
+  const normalized = input.scopes.map((scope) => scope.toLowerCase());
+  const hasRepo = normalized.some((scope) => scope.includes('repo') || scope.includes('repository'));
+  const hasWrite = normalized.some((scope) => /(?:write|push|contents:write|metadata:write)/u.test(scope));
+  const hasRead = normalized.some((scope) => /(?:read|pull|contents:read|metadata:read)/u.test(scope));
+  if (hasRepo && hasWrite) return 'repo_read_write';
+  if (hasRepo || hasRead) return 'repo_read_only';
+  return 'metadata_only';
+}
+
 function stableProofRoot(label: string, value: unknown) {
   return createHash('sha256')
     .update(`${label}:${stableStringify(toAuxillariesJsonSafe(value))}`)