@orchestrator-claude/definitions 3.43.1 → 3.44.1

package/hooks/lib/api-client.ts

@@ -123,12 +123,27 @@ const API_URL = process.env.ORCHESTRATOR_API_URL || 'http://localhost:3001';
 // `system` tier account (level 4, ABOVE admin) rather than admin — the
 // env-override chain is preserved verbatim so an explicit
 // ORCHESTRATOR_ADMIN_EMAIL/ORCHESTRATOR_AUTH_EMAIL still wins.
-const AUTH_EMAIL =
-  process.env.ORCHESTRATOR_ADMIN_EMAIL ||
-  process.env.ORCHESTRATOR_AUTH_EMAIL ||
-  'system@orchestrator.local';
-const AUTH_PASSWORD =
-  process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || 'system123';
+const DEFAULT_AUTH_EMAIL = 'system@orchestrator.local';
+// TD-267 A1 (S572): there is NO default password. The credential is read
+// lazily, at login time, and a password that is unset, empty or
+// whitespace-only counts as absent — in which case login() makes no network
+// call at all and getToken() returns null (each hook keeps the posture it
+// already has for "no token"). The client never invents a credential.
+const MISSING_CREDENTIAL_MESSAGE =
+  'no credential configured (ORCHESTRATOR_ADMIN_PASSWORD / ORCHESTRATOR_AUTH_PASSWORD unset or empty) - login not attempted';
+let missingCredentialLogged = false;
+
+function resolveAuthCredentials(): { email: string; password: string } | null {
+  const password =
+    (process.env.ORCHESTRATOR_ADMIN_PASSWORD ?? '').trim() ||
+    (process.env.ORCHESTRATOR_AUTH_PASSWORD ?? '').trim();
+  if (!password) return null;
+  const email =
+    process.env.ORCHESTRATOR_ADMIN_EMAIL ||
+    process.env.ORCHESTRATOR_AUTH_EMAIL ||
+    DEFAULT_AUTH_EMAIL;
+  return { email, password };
+}
 // Mutable (not const): RFC-040 Operator Multi-Project, Slice 5 (C5) lazily
 // resolves this once per process when the env var is absent — see
 // ensureProjectIdResolved() below.
@@ -338,6 +353,14 @@ async function login(): Promise<string | null> {
   // the server ignores X-Project-ID on this route entirely, so login can
   // always proceed and PROJECT_ID is resolved afterwards, once a Bearer
   // token is available (see ensureProjectIdResolved, called from getToken()).
+  const credentials = resolveAuthCredentials();
+  if (credentials === null) {
+    if (!missingCredentialLogged) {
+      missingCredentialLogged = true;
+      log('API-CLIENT', MISSING_CREDENTIAL_MESSAGE);
+    }
+    return null;
+  }
   try {
     const resp = await fetch(`${API_URL}/api/v1/auth/login`, {
       method: 'POST',
@@ -345,7 +368,7 @@ async function login(): Promise<string | null> {
         'Content-Type': 'application/json',
         'X-Project-ID': PROJECT_ID,
       },
-      body: JSON.stringify({ email: AUTH_EMAIL, password: AUTH_PASSWORD }),
+      body: JSON.stringify({ email: credentials.email, password: credentials.password }),
       signal: AbortSignal.timeout(5000),
     });
     if (!resp.ok) return null;
@@ -1088,35 +1111,138 @@ export async function getGateCellMode(
   }
 }
 
+/**
+ * Outcome of `GET /api/v1/artifact-content/:wf/adversarial_review`, classified
+ * so the caller can tell WHY there is no usable verdict (TD-374) and decide.
+ *
+ * - `ok`: verdict string + `iteration` parsed from a canonical decimal string.
+ * - `absent`: HTTP 404 (no artifact yet).
+ * - `malformed`: HTTP 200 whose body carries no decidable verdict. `iteration_invalid`
+ *   here means `iteration` is absent or not a string.
+ * - `iteration_rejected`: verdict is a valid string but `iteration` is a string that
+ *   fails the grammar (TD-375). Distinct kind on purpose: the caller must decide, a
+ *   `malformed` branch handled as fail-open would reopen the hole in silence.
+ * - `error`: no usable response (HTTP != 200/404, timeout, network, unexpected).
+ */
+export type AdversarialVerdictResult =
+  | { kind: 'ok'; verdict: string; iteration: number }
+  | { kind: 'absent' }
+  | {
+      kind: 'malformed';
+      reason:
+        | 'body_not_json'
+        | 'body_not_object'
+        | 'custom_metadata_missing'
+        | 'verdict_invalid'
+        | 'iteration_invalid';
+      detail?: string;
+    }
+  | { kind: 'iteration_rejected'; verdict: string; detail: string }
+  | { kind: 'error'; reason: 'http' | 'timeout' | 'network' | 'unexpected'; status?: number };
+
+type StatusFetch =
+  | { readonly kind: 'response'; readonly resp: Response }
+  | { readonly kind: 'error'; readonly reason: 'timeout' | 'network' };
+
+/**
+ * Same request as `apiGet` (URL, headers, 5s timeout) but keeps the HTTP
+ * status and the failure cause that `apiGet` collapses into `null`.
+ * `apiGet` itself is intentionally left untouched.
+ */
+async function apiGetWithStatus(path: string, token: string): Promise<StatusFetch> {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'X-Project-ID': PROJECT_ID,
+      },
+      signal: AbortSignal.timeout(5000),
+    });
+    return { kind: 'response', resp };
+  } catch (err) {
+    const name: unknown = typeof err === 'object' && err !== null && 'name' in err ? err.name : '';
+    const timedOut = name === 'TimeoutError' || name === 'AbortError';
+    return { kind: 'error', reason: timedOut ? 'timeout' : 'network' };
+  }
+}
+
+/** `JSON.stringify(raw)` capped at 40 chars; undefined when raw has no JSON form. */
+function iterationDetail(raw: unknown): string | undefined {
+  // JSON.stringify yields undefined for undefined/functions/symbols despite its typing.
+  const json = JSON.stringify(raw) as string | undefined;
+  return json === undefined ? undefined : json.slice(0, 40);
+}
+
+/** Canonical decimal grammar for `iteration` (TD-375): ASCII digits, safe integer. */
+function parseIteration(raw: string): number | null {
+  if (!/^[0-9]+$/.test(raw)) return null;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) ? value : null;
+}
+
+function classifyIteration(verdict: string, rawIteration: unknown): AdversarialVerdictResult {
+  if (typeof rawIteration !== 'string') {
+    const detail = iterationDetail(rawIteration);
+    return detail === undefined
+      ? { kind: 'malformed', reason: 'iteration_invalid' }
+      : { kind: 'malformed', reason: 'iteration_invalid', detail };
+  }
+  const iteration = parseIteration(rawIteration);
+  if (iteration === null) {
+    return { kind: 'iteration_rejected', verdict, detail: iterationDetail(rawIteration) ?? '' };
+  }
+  return { kind: 'ok', verdict, iteration };
+}
+
+function classifyAdversarialBody(body: unknown): AdversarialVerdictResult {
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    return { kind: 'malformed', reason: 'body_not_object' };
+  }
+  const metadata: unknown = 'metadata' in body ? body.metadata : undefined;
+  const customMetadata: unknown =
+    typeof metadata === 'object' && metadata !== null && 'customMetadata' in metadata
+      ? metadata.customMetadata
+      : undefined;
+  if (typeof customMetadata !== 'object' || customMetadata === null) {
+    return { kind: 'malformed', reason: 'custom_metadata_missing' };
+  }
+  const verdict: unknown = 'verdict' in customMetadata ? customMetadata.verdict : undefined;
+  if (typeof verdict !== 'string') return { kind: 'malformed', reason: 'verdict_invalid' };
+  const rawIteration: unknown =
+    'iteration' in customMetadata ? customMetadata.iteration : undefined;
+  return classifyIteration(verdict, rawIteration);
+}
+
 /**
  * Retrieves the adversarial review verdict and iteration for a workflow.
- * Calls GET /api/v1/artifact-content/:workflowId/adversarial_review.
- * The API serves the fields in metadata.customMetadata (strings — S3
- * x-amz-meta-* headers only carry strings), so `iteration` is coerced:
- * accepted only as a non-blank string whose Number() is finite (TD-331).
- * Returns null when artifact is absent (404), on 5xx, timeout, or missing /
- * malformed customMetadata fields (fail-open — gate is not enforced when
- * artifact is absent). The pre-TD-331 flat metadata.{verdict,iteration}
- * shape is NOT read (RF-003).
+ * Calls GET /api/v1/artifact-content/:workflowId/adversarial_review and
+ * classifies the outcome (see AdversarialVerdictResult); it never rejects and
+ * never returns null. The API serves the fields in metadata.customMetadata
+ * (strings: S3 x-amz-meta-* headers only carry strings), so `iteration` is
+ * accepted only as a canonical decimal string (/^[0-9]+$/, safe integer). The
+ * pre-TD-331 flat metadata.{verdict,iteration} shape is NOT read (RF-003).
  */
 export async function getAdversarialVerdict(
   workflowId: string,
   token: string
-): Promise<{ verdict: string; iteration: number } | null> {
+): Promise<AdversarialVerdictResult> {
   try {
-    const resp = await apiGet<{
-      content?: string;
-      metadata?: { customMetadata?: Record<string, unknown> };
-    }>(`/api/v1/artifact-content/${workflowId}/adversarial_review`, token);
-    if (!resp) return null;
-    const { verdict, iteration: rawIteration } = resp.metadata?.customMetadata ?? {};
-    if (typeof verdict !== 'string' || typeof rawIteration !== 'string') return null;
-    if (rawIteration.trim() === '') return null;
-    const iteration = Number(rawIteration);
-    if (!Number.isFinite(iteration)) return null;
-    return { verdict, iteration };
+    const got = await apiGetWithStatus(
+      `/api/v1/artifact-content/${workflowId}/adversarial_review`,
+      token
+    );
+    if (got.kind === 'error') return got;
+    if (got.resp.status === 404) return { kind: 'absent' };
+    if (!got.resp.ok) return { kind: 'error', reason: 'http', status: got.resp.status };
+    let body: unknown;
+    try {
+      body = await got.resp.json();
+    } catch {
+      return { kind: 'malformed', reason: 'body_not_json' };
+    }
+    return classifyAdversarialBody(body);
   } catch {
-    return null;
+    return { kind: 'error', reason: 'unexpected' };
   }
 }