Commit 2a29de7502cdd02686bda7d12fb2671060fd1979 | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-06-20 20:20:12-07:00
committer	GitHub <noreply@github.com> 2026-06-20 20:20:12-07:00
log	2a29de7502cdd02686bda7d12fb2671060fd1979
tree	407720a2cc764f8010f61b9dffdb8ead453e847c
parent	8c1605b38327176bae94c33bbc6de86e8b09fe02
signature	Signed by PGP key B5690EEEBB952194

[codex] Structure primary auth validation failures (#3471)

Co-authored-by: codex <codex@users.noreply.github.com>

4 files changed, 146 insertions(+), 81 deletions(-)

apps
- web
  - src
    authBootstrap.test.ts
    environments
    primary
    auth.ts
    context.ts
    index.ts

apps/web/src/authBootstrap.test.ts+76-26

 @@ -71,6 +71,18 @@ function installTestBrowser(url: string) {
   return testWindow;
 }
+function installDesktopBootstrap() {
+  const testWindow = installTestBrowser("http://localhost/");
+  testWindow.desktopBridge = {
+    getLocalEnvironmentBootstrap: () => ({
+      label: "Local environment",
+      httpBaseUrl: "http://localhost:3773",
+      wsBaseUrl: "ws://localhost:3773",
+      bootstrapToken: "desktop-bootstrap-token",
+    }),
+  } as DesktopBridge;
+}
 function sequence<A>(...values: ReadonlyArray<A>) {
   let index = 0;
   return () => values[Math.min(index++, values.length - 1)]!;
 @@ -131,15 +143,7 @@ describe("resolveInitialServerAuthGateState", () => {
       browserSession: () => Effect.succeed(browserSession(["orchestration:read", "access:write"])),
     });
-    const testWindow = installTestBrowser("http://localhost/");
+    installDesktopBootstrap();
-    testWindow.desktopBridge = {
-      getLocalEnvironmentBootstrap: () => ({
-        label: "Local environment",
-        httpBaseUrl: "http://localhost:3773",
-        wsBaseUrl: "ws://localhost:3773",
-        bootstrapToken: "desktop-bootstrap-token",
-      }),
-    } as DesktopBridge;
     const { resolveInitialServerAuthGateState } = await import("./environments/primary");
 @@ -289,6 +293,23 @@ describe("resolveInitialServerAuthGateState", () => {
     expect(testApi.calls.session).toBe(2);
   });
+  it("rejects a blank pairing token with a structured validation error", async () => {
+    const { PrimaryEnvironmentPairingCredentialRequiredError, submitServerAuthCredential } =
+      await import("./environments/primary/auth");
+    const error = await submitServerAuthCredential("   ").then(
+      () => null,
+      (failure: unknown) => failure,
+    );
+    expect(error).toBeInstanceOf(PrimaryEnvironmentPairingCredentialRequiredError);
+    expect(error).toMatchObject({
+      _tag: "PrimaryEnvironmentPairingCredentialRequiredError",
+      providedLength: 3,
+      message: "Enter a pairing token to continue.",
+    });
+  });
   it("surfaces a friendly error message when an invalid pairing token is submitted", async () => {
     const cause = new EnvironmentAuthInvalidError({
       code: "auth_invalid",
 @@ -299,7 +320,7 @@ describe("resolveInitialServerAuthGateState", () => {
       browserSession: () => Effect.fail(cause),
     });
-    const { isPrimaryEnvironmentRequestError, submitServerAuthCredential } =
+    const { isPrimaryEnvironmentPairingCredentialRejectedError, submitServerAuthCredential } =
       await import("./environments/primary");
     const error = await submitServerAuthCredential("bad-token").then(
 @@ -307,14 +328,13 @@ describe("resolveInitialServerAuthGateState", () => {
       (failure: unknown) => failure,
     );
     expect(error).toMatchObject({
-      _tag: "PrimaryEnvironmentRequestError",
+      _tag: "PrimaryEnvironmentPairingCredentialRejectedError",
-      operation: "exchange-bootstrap-credential",
+      providedLength: 9,
-      status: 401,
+      message: "Invalid pairing token. Check the token and try again.",
-      detail: "Invalid pairing token. Check the token and try again.",
     });
-    expect(isPrimaryEnvironmentRequestError(error)).toBe(true);
+    expect(isPrimaryEnvironmentPairingCredentialRejectedError(error)).toBe(true);
-    if (!isPrimaryEnvironmentRequestError(error)) {
+    if (!isPrimaryEnvironmentPairingCredentialRejectedError(error)) {
-      throw new Error("Expected a structured primary environment request error.");
+      throw new Error("Expected a structured rejected pairing credential error.");
     }
     expect(error.cause).toMatchObject({
       _tag: "EnvironmentAuthInvalidError",
 @@ -325,6 +345,22 @@ describe("resolveInitialServerAuthGateState", () => {
     expect(testApi.calls.browserSession).toEqual([{ credential: "bad-token" }]);
   });
+  it("derives primary request messages from structural request context", async () => {
+    const cause = new Error("private transport detail");
+    const { PrimaryEnvironmentRequestError } = await import("./environments/primary");
+    const error = PrimaryEnvironmentRequestError.fromCause({
+      operation: "list-pairing-links",
+      cause,
+    });
+    expect(error.status).toBe(500);
+    expect(error.cause).toBe(cause);
+    expect(error.message).toBe(
+      "Primary environment request failed during list-pairing-links (HTTP 500).",
+    );
+    expect(error.message).not.toContain(cause.message);
+  });
   it("waits for the authenticated session to become observable after silent desktop bootstrap", async () => {
     vi.useFakeTimers();
     const nextSession = sequence(
 @@ -337,15 +373,7 @@ describe("resolveInitialServerAuthGateState", () => {
       browserSession: () => Effect.succeed(browserSession(["orchestration:read", "access:write"])),
     });
-    const testWindow = installTestBrowser("http://localhost/");
+    installDesktopBootstrap();
-    testWindow.desktopBridge = {
-      getLocalEnvironmentBootstrap: () => ({
-        label: "Local environment",
-        httpBaseUrl: "http://localhost:3773",
-        wsBaseUrl: "ws://localhost:3773",
-        bootstrapToken: "desktop-bootstrap-token",
-      }),
-    } as DesktopBridge;
     const { resolveInitialServerAuthGateState } = await import("./environments/primary");
 @@ -356,6 +384,28 @@ describe("resolveInitialServerAuthGateState", () => {
     expect(testApi.calls.session).toBe(3);
   });
+  it("preserves the timeout message when a bootstrapped session never becomes observable", async () => {
+    vi.useFakeTimers();
+    const testApi = await installAuthApi({
+      session: () => unauthenticatedSession(DESKTOP_AUTH),
+      browserSession: () => Effect.succeed(browserSession(["orchestration:read", "access:write"])),
+    });
+    installDesktopBootstrap();
+    const { resolveInitialServerAuthGateState } = await import("./environments/primary");
+    const gateStatePromise = resolveInitialServerAuthGateState();
+    await vi.advanceTimersByTimeAsync(2_000);
+    await expect(gateStatePromise).resolves.toEqual({
+      status: "requires-auth",
+      auth: DESKTOP_AUTH,
+      errorMessage: "Timed out waiting for authenticated session after bootstrap.",
+    });
+    expect(testApi.calls.browserSession).toEqual([{ credential: "desktop-bootstrap-token" }]);
+  });
   it("memoizes the authenticated gate state after the first successful read", async () => {
     const testApi = await installAuthApi({
       session: sequence(authenticatedSession(LOOPBACK_AUTH), unauthenticatedSession(LOOPBACK_AUTH)),

apps/web/src/environments/primary/auth.ts+68-54

 @@ -40,7 +40,6 @@ export class PrimaryEnvironmentRequestError extends Schema.TaggedErrorClass<Prim
   {
     operation: PrimaryEnvironmentRequestOperation,
     status: Schema.Number,
-    detail: Schema.String,
     pairingLinkId: Schema.optional(Schema.String),
     sessionId: Schema.optional(Schema.String),
     cause: Schema.Defect(),
 @@ -49,17 +48,13 @@ export class PrimaryEnvironmentRequestError extends Schema.TaggedErrorClass<Prim
   static fromCause(input: {
     readonly operation: PrimaryEnvironmentRequestOperation;
     readonly cause: unknown;
-    readonly fallbackMessage: (status: number) => string;
-    readonly formatDetail?: (detail: string, status: number) => string;
     readonly pairingLinkId?: string;
     readonly sessionId?: string;
   }): PrimaryEnvironmentRequestError {
     const status = readHttpApiStatus(input.cause) ?? 500;
-    const rawDetail = readHttpApiErrorMessage(input.cause, input.fallbackMessage(status));
     return new PrimaryEnvironmentRequestError({
       operation: input.operation,
       status,
-      detail: input.formatDetail?.(rawDetail, status) ?? rawDetail,
       ...(input.pairingLinkId !== undefined ? { pairingLinkId: input.pairingLinkId } : {}),
       ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
       cause: input.cause,
 @@ -67,11 +62,59 @@ export class PrimaryEnvironmentRequestError extends Schema.TaggedErrorClass<Prim
   }
   override get message(): string {
-    return this.detail;
+    return `Primary environment request failed during ${this.operation} (HTTP ${this.status}).`;
   }
 }
 export const isPrimaryEnvironmentRequestError = Schema.is(PrimaryEnvironmentRequestError);
+export class PrimaryEnvironmentPairingCredentialRejectedError extends Schema.TaggedErrorClass<PrimaryEnvironmentPairingCredentialRejectedError>()(
+  "PrimaryEnvironmentPairingCredentialRejectedError",
+  {
+    providedLength: Schema.Number,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return "Invalid pairing token. Check the token and try again.";
+  }
+}
+export const isPrimaryEnvironmentPairingCredentialRejectedError = Schema.is(
+  PrimaryEnvironmentPairingCredentialRejectedError,
+);
+export class PrimaryEnvironmentAuthSessionTimeoutError extends Schema.TaggedErrorClass<PrimaryEnvironmentAuthSessionTimeoutError>()(
+  "PrimaryEnvironmentAuthSessionTimeoutError",
+  {
+    timeoutMs: Schema.Number,
+    elapsedMs: Schema.Number,
+  },
+) {
+  override get message(): string {
+    return "Timed out waiting for authenticated session after bootstrap.";
+  }
+}
+export const isPrimaryEnvironmentAuthSessionTimeoutError = Schema.is(
+  PrimaryEnvironmentAuthSessionTimeoutError,
+);
+export class PrimaryEnvironmentPairingCredentialRequiredError extends Schema.TaggedErrorClass<PrimaryEnvironmentPairingCredentialRequiredError>()(
+  "PrimaryEnvironmentPairingCredentialRequiredError",
+  {
+    providedLength: Schema.Number,
+  },
+) {
+  override get message(): string {
+    return "Enter a pairing token to continue.";
+  }
+}
+export const isPrimaryEnvironmentPairingCredentialRequiredError = Schema.is(
+  PrimaryEnvironmentPairingCredentialRequiredError,
+);
 const isEnvironmentHttpCommonError = Schema.is(EnvironmentHttpCommonError);
 export interface ServerPairingLinkRecord {
 @@ -151,7 +194,6 @@ export async function fetchSessionState(): Promise<AuthSessionState> {
       throw PrimaryEnvironmentRequestError.fromCause({
         operation: "fetch-session-state",
         cause: error,
-        fallbackMessage: (status) => `Failed to load server auth session state (${status}).`,
       });
     }
   });
 @@ -180,42 +222,6 @@ function readEnvironmentHttpErrorStatus(error: EnvironmentHttpCommonErrorType):
   }
 }
-function readHttpApiErrorMessage(error: unknown, fallbackMessage: string): string {
-  if (!isEnvironmentHttpCommonError(error)) {
-    return fallbackMessage;
-  }
-  switch (error._tag) {
-    case "EnvironmentAuthInvalidError":
-      return error.reason === "missing_credential"
-        ? "Authentication required."
-        : "Invalid bootstrap credential.";
-    case "EnvironmentRequestInvalidError":
-      return error.reason === "invalid_scope"
-        ? "Requested token scope is invalid."
-        : "Requested scope exceeds the bootstrap credential grant.";
-    case "EnvironmentScopeRequiredError":
-      return `The authenticated token is missing required scope: ${error.requiredScope}.`;
-    case "EnvironmentOperationForbiddenError":
-      return "This operation is not allowed for the current session.";
-    case "EnvironmentInternalError":
-      return fallbackMessage;
-  }
-}
-const INVALID_BOOTSTRAP_CREDENTIAL_MESSAGES = new Set([
-  "Invalid bootstrap credential.",
-  "Unknown bootstrap credential.",
-]);
-function toFriendlyBootstrapErrorMessage(status: number, message: string): string {
-  const trimmedMessage = message.trim();
-  if (status === 401 && INVALID_BOOTSTRAP_CREDENTIAL_MESSAGES.has(trimmedMessage)) {
-    return "Invalid pairing token. Check the token and try again.";
-  }
-  return trimmedMessage;
-}
 async function exchangeBootstrapCredential(credential: string): Promise<AuthBrowserSessionResult> {
   return retryTransientBootstrap(async () => {
     try {
 @@ -225,11 +231,19 @@ async function exchangeBootstrapCredential(credential: string): Promise<AuthBrow
         ),
       );
     } catch (error) {
+      if (
+        isEnvironmentHttpCommonError(error) &&
+        error._tag === "EnvironmentAuthInvalidError" &&
+        error.reason === "invalid_credential"
+      ) {
+        throw new PrimaryEnvironmentPairingCredentialRejectedError({
+          providedLength: credential.length,
+          cause: error,
+        });
+      }
       throw PrimaryEnvironmentRequestError.fromCause({
         operation: "exchange-bootstrap-credential",
         cause: error,
-        fallbackMessage: (status) => `Failed to bootstrap auth session (${status}).`,
-        formatDetail: (detail, status) => toFriendlyBootstrapErrorMessage(status, detail),
       });
     }
   });
 @@ -244,8 +258,12 @@ async function waitForAuthenticatedSessionAfterBootstrap(): Promise<AuthSessionS
       return session;
     }
-    if (Date.now() - startedAt >= AUTH_SESSION_ESTABLISH_TIMEOUT_MS) {
+    const elapsedMs = Date.now() - startedAt;
-      throw new Error("Timed out waiting for authenticated session after bootstrap.");
+    if (elapsedMs >= AUTH_SESSION_ESTABLISH_TIMEOUT_MS) {
+      throw new PrimaryEnvironmentAuthSessionTimeoutError({
+        timeoutMs: AUTH_SESSION_ESTABLISH_TIMEOUT_MS,
+        elapsedMs,
+      });
     }
     await waitForBootstrapRetry(AUTH_SESSION_ESTABLISH_STEP_MS);
 @@ -323,7 +341,9 @@ async function bootstrapServerAuth(): Promise<ServerAuthGateState> {
 export async function submitServerAuthCredential(credential: string): Promise<void> {
   const trimmedCredential = credential.trim();
   if (!trimmedCredential) {
-    throw new Error("Enter a pairing token to continue.");
+    throw new PrimaryEnvironmentPairingCredentialRequiredError({
+      providedLength: credential.length,
+    });
   }
   resolvedAuthenticatedGateState = null;
 @@ -355,7 +375,6 @@ export async function createServerPairingCredential(input?: {
     throw PrimaryEnvironmentRequestError.fromCause({
       operation: "create-pairing-credential",
       cause: error,
-      fallbackMessage: (status) => `Failed to create pairing credential (${status}).`,
     });
   }
 }
 @@ -396,7 +415,6 @@ export async function listServerPairingLinks(): Promise<ReadonlyArray<ServerPair
     throw PrimaryEnvironmentRequestError.fromCause({
       operation: "list-pairing-links",
       cause: error,
-      fallbackMessage: (status) => `Failed to load pairing links (${status}).`,
     });
   }
 }
 @@ -413,7 +431,6 @@ export async function revokeServerPairingLink(id: string): Promise<void> {
       operation: "revoke-pairing-link",
       pairingLinkId: id,
       cause: error,
-      fallbackMessage: (status) => `Failed to revoke pairing link (${status}).`,
     });
   }
 }
 @@ -446,7 +463,6 @@ export async function listServerClientSessions(): Promise<
     throw PrimaryEnvironmentRequestError.fromCause({
       operation: "list-client-sessions",
       cause: error,
-      fallbackMessage: (status) => `Failed to load paired clients (${status}).`,
     });
   }
 }
 @@ -465,7 +481,6 @@ export async function revokeServerClientSession(sessionId: AuthSessionId): Promi
       operation: "revoke-client-session",
       sessionId,
       cause: error,
-      fallbackMessage: (status) => `Failed to revoke client session (${status}).`,
     });
   }
 }
 @@ -482,7 +497,6 @@ export async function revokeOtherServerClientSessions(): Promise<number> {
     throw PrimaryEnvironmentRequestError.fromCause({
       operation: "revoke-other-client-sessions",
       cause: error,
-      fallbackMessage: (status) => `Failed to revoke other client sessions (${status}).`,
     });
   }
 }

apps/web/src/environments/primary/context.ts-1

...	@@ -46,7 +46,6 @@ async function fetchPrimaryEnvironmentDescriptor(): Promise<ExecutionEnvironment	...	@@ -46,7 +46,6 @@ async function fetchPrimaryEnvironmentDescriptor(): Promise<ExecutionEnvironment
46	throw PrimaryEnvironmentRequestError.fromCause({	46	throw PrimaryEnvironmentRequestError.fromCause({
47	operation: "fetch-environment-descriptor",	47	operation: "fetch-environment-descriptor",
48	cause: error,	48	cause: error,
49	fallbackMessage: (status) => `Failed to load server environment descriptor (${status}).`,
50	});	49	});
51	}	50	}
52		51

apps/web/src/environments/primary/index.ts+2

 @@ -16,10 +16,12 @@ export {
 export {
   createServerPairingCredential,
   fetchSessionState,
+  isPrimaryEnvironmentPairingCredentialRejectedError,
   isPrimaryEnvironmentRequestError,
   listServerClientSessions,
   listServerPairingLinks,
   peekPairingTokenFromUrl,
+  PrimaryEnvironmentPairingCredentialRejectedError,
   PrimaryEnvironmentRequestError,
   resolveInitialServerAuthGateState,
   revokeOtherServerClientSessions,