@superblocksteam/shared 0.9609.8 → 0.9611.1

package/src/types/policyGate/index.ts

@@ -1,4 +1,7 @@
 import type { ReviewFindingCategory, ReviewFindingConfidence, ReviewFindingSeverity } from '../reviewPolicy/index.js';
+import { MAX_POLICY_GATE_RUN_ATTEMPTS } from './errors.js';
+
+export * from './errors.js';
 
 /**
  * @deprecated Use the `superblocks.policy-gates.security-scans.enabled` LaunchDarkly flag instead.
@@ -28,6 +31,7 @@ export type PolicyGateReadinessFindingSummary = {
 export type PolicyGateReadinessFinding = {
   blocking: boolean;
   humanSummary?: string | null;
+  /** Same contract as `ReviewFindingDto.locations`: primary location first. */
   locationsJson?: unknown[];
   remediationHintJson?: Record<string, unknown>;
   severity: 'critical' | 'high' | 'info' | 'low' | 'medium';
@@ -60,7 +64,7 @@ export type PolicyGateReadinessItem = {
   findingSummary: PolicyGateReadinessFindingSummary;
   itemId: string;
   itemType: 'security_agent' | 'security_scan';
-  mode: 'advisory' | 'approval' | 'blocking' | 'report_only';
+  mode: 'advisory' | 'approval' | 'blocking' | 'blocking_with_exceptions' | 'report_only';
   policyId: string;
   policyVersionId: string;
   progress?: PolicyGateScanProgress;
@@ -70,6 +74,9 @@ export type PolicyGateReadinessItem = {
   status: PolicyGateReadinessItemStatus;
 };
 
+// An outcome that stops the publish and cannot be waived. A gate that errored
+// counts the same as findings: it never cleared the code, and this mode grants
+// no exceptions.
 export function isHardBlockingPolicyItem(item: Pick<PolicyGateReadinessItem, 'mode' | 'status'>): boolean {
   if (item.mode !== 'blocking' && item.mode !== 'approval') {
     return false;
@@ -77,15 +84,38 @@ export function isHardBlockingPolicyItem(item: Pick<PolicyGateReadinessItem, 'mo
   return item.status === 'blocked' || item.status === 'failed';
 }
 
+/**
+ * An outcome that stops the publish but that "Publish anyway" may release. A
+ * gate that errored is waivable here because the admin picked the mode with
+ * exceptions; note this waives a review that never produced findings, not one
+ * whose findings the publisher read.
+ */
+export function isWaivablePolicyItem(item: Pick<PolicyGateReadinessItem, 'mode' | 'status'>): boolean {
+  return item.mode === 'blocking_with_exceptions' && (item.status === 'blocked' || item.status === 'failed');
+}
+
+export function isPublishHoldingPolicyItem(item: Pick<PolicyGateReadinessItem, 'mode' | 'status'>): boolean {
+  return isWaivablePolicyItem(item);
+}
+
 /**
  * Whether every item is an outcome an acknowledged "Publish anyway" hold is
- * allowed to bypass. `missing`/`stale`/`running`/`failed`/`approval_required`
- * mean some gate has not finished or hard-blocks unconditionally; an ack
- * granted while any of those exist could waive a review that never happened.
+ * allowed to bypass. `missing`/`stale`/`running`/`approval_required` mean some
+ * gate has not finished or hard-blocks unconditionally; an ack granted while
+ * any of those exist could waive a gate that is still deciding. A `blocked` or
+ * errored advisory item is settled without a waiver. Only
+ * `blocking_with_exceptions` outcomes are bypassable.
  */
-export function areReadinessItemsAckEligible(items: Pick<PolicyGateReadinessItem, 'status'>[]): boolean {
+export function areReadinessItemsAckEligible(items: Pick<PolicyGateReadinessItem, 'mode' | 'status'>[]): boolean {
   return (
-    items.length > 0 && items.every((item) => item.status === 'blocked' || item.status === 'passed' || item.status === 'advisory_findings')
+    items.length > 0 &&
+    items.every(
+      (item) =>
+        item.status === 'passed' ||
+        item.status === 'advisory_findings' ||
+        isPublishHoldingPolicyItem(item) ||
+        (item.mode === 'advisory' && (item.status === 'blocked' || item.status === 'failed'))
+    )
   );
 }
 
@@ -175,3 +205,11 @@ export type ScanScopeJson = {
   priorReviewRunId?: string;
   unifiedDiff: string;
 };
+
+export function countFailedPolicyGateRuns(item: Pick<PolicyGateReadinessItem, 'runs'>): number {
+  return (item.runs ?? []).filter((run) => run.status === 'failed' && run.errorCode !== 'canceled').length;
+}
+
+export function isPolicyGateItemExhausted(item: Pick<PolicyGateReadinessItem, 'mode' | 'runs' | 'status'>): boolean {
+  return item.status === 'failed' && item.mode !== 'advisory' && countFailedPolicyGateRuns(item) >= MAX_POLICY_GATE_RUN_ATTEMPTS;
+}

package/src/types/publishPipeline/displayNames.test.ts

@@ -53,10 +53,10 @@ describe('publishStepDisplayName', () => {
   });
 
   test('gives the policy step an active phrasing while it runs, and its plain name otherwise', () => {
-    expect(publishStepDisplayName('policy_gates', 'pending')).toBe('Pre-Publish Policies');
-    expect(publishStepDisplayName('policy_gates', 'in_progress')).toBe('Running Pre-Publish Policies…');
-    expect(publishStepDisplayName('policy_gates', 'passed')).toBe('Pre-Publish Policies');
-    expect(publishStepDisplayName('policy_gates', 'failed')).toBe('Pre-Publish Policies failed');
+    expect(publishStepDisplayName('policy_gates', 'pending')).toBe('Run policy agents');
+    expect(publishStepDisplayName('policy_gates', 'in_progress')).toBe('Running policy agents…');
+    expect(publishStepDisplayName('policy_gates', 'passed')).toBe('Run policy agents');
+    expect(publishStepDisplayName('policy_gates', 'failed')).toBe('Run policy agents failed');
   });
 
   test('has a label for every kind so a new step cannot render an empty row', () => {
@@ -78,7 +78,7 @@ describe('publishStepDependencyName', () => {
     expect(publishStepDependencyName('build')).toBe('the application build');
     expect(publishStepDependencyName('database_migration')).toBe('schema migrations');
     expect(publishStepDependencyName('database_provisioning')).toBe('database provisioning');
-    expect(publishStepDependencyName('policy_gates')).toBe('Pre-Publish Policies');
+    expect(publishStepDependencyName('policy_gates')).toBe('policy agents');
     expect(publishStepDependencyName('publish')).toBe('publishing');
   });
 

package/src/types/publishPipeline/displayNames.ts

@@ -19,8 +19,8 @@ type StepLabels = {
 /**
  * A step reads as an action: its plain, not-yet-running name (`idle`) while it
  * waits, its active phrasing while it runs, and its past tense once done. The
- * policy step is named after the policies it checks rather than an action, so
- * its idle and done names are the same and only its running name gains a verb.
+ * policy step uses the same idle and done name (`Run policy agents`) and only
+ * its running name gains a verb.
  */
 const STEP_LABELS: Record<PublishStepKind, StepLabels> = {
   build: {
@@ -42,10 +42,10 @@ const STEP_LABELS: Record<PublishStepKind, StepLabels> = {
     idle: 'Provision database(s)'
   },
   policy_gates: {
-    active: 'Running Pre-Publish Policies',
-    dependency: 'Pre-Publish Policies',
-    done: 'Pre-Publish Policies',
-    idle: 'Pre-Publish Policies'
+    active: 'Running policy agents',
+    dependency: 'policy agents',
+    done: 'Run policy agents',
+    idle: 'Run policy agents'
   },
   publish: {
     active: 'Publishing',

package/src/types/publishPipeline/index.ts

@@ -15,8 +15,8 @@ export type PublishStepKind = 'build' | 'database_migration' | 'database_provisi
 
 /**
  * Domain-agnostic status. Ordered here by roll-up precedence (worst first).
- * `blocked` means this step's own check failed (remediation). Waiting on an
- * earlier step is `pending` with optional `blockedBy`.
+ * `blocked` means this step's own check failed (remediation). Waiting on a
+ * declared dependency is `pending` with optional `blockedBy`.
  * `skipped` is a visible N/A row (e.g. Build when the app has no native-git remote).
  */
 export type PublishStepStatus =
@@ -52,7 +52,7 @@ export type PublishStep = {
   description?: string;
   /** Short subtitle / one-line error. */
   summary?: string;
-  /** When status is pending and waiting on earlier steps. */
+  /** When status is pending and waiting on declared dependencies that are not yet clear. */
   blockedBy?: PublishStepKind[];
   /** Machine code when blocked/failed (e.g. POLICY_GATE_BLOCKED). */
   blockingReason?: string;

package/src/types/publishPipeline/plan.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'vitest';
 
-import type { PublishStep, PublishStepKind, PublishStepStatus } from './index.js';
-import { applyBlockedByEligibility, buildPublishPlan, orderPublishSteps, rollUpPublishPlan } from './plan.js';
+import type { PublishStep, PublishStepStatus } from './index.js';
+import { buildPublishPlan, orderPublishSteps, rollUpPublishPlan } from './plan.js';
 
 const TARGET = { applicationId: 'app-1', commitId: 'commit-1' };
 
@@ -81,111 +81,10 @@ describe('orderPublishSteps', () => {
   });
 });
 
-describe('applyBlockedByEligibility', () => {
-  test('marks later pending steps as blockedBy earlier unclear steps', () => {
-    const steps = applyBlockedByEligibility([
-      step({ id: 'build', kind: 'build', status: 'in_progress' }),
-      step({ id: 'publish', kind: 'publish', status: 'pending' })
-    ]);
-    expect(steps[1].blockedBy).toEqual<PublishStepKind[]>(['build']);
-    expect(steps[1].status).toBe('pending');
-  });
-
-  test('does not overwrite a step that already failed', () => {
-    const steps = applyBlockedByEligibility([
-      step({ id: 'build', kind: 'build', status: 'failed' }),
-      step({ id: 'publish', kind: 'publish', status: 'failed' })
-    ]);
-    expect(steps[1].blockedBy).toBeUndefined();
-    expect(steps[1].status).toBe('failed');
-  });
-
-  test('holds an in_progress publish as pending until earlier policy gates clear', () => {
-    const steps = applyBlockedByEligibility([
-      step({
-        id: 'policy_gates:before_deploy',
-        kind: 'policy_gates',
-        status: 'in_progress',
-        displayName: 'Pre-Publish Policies'
-      }),
-      step({
-        id: 'publish',
-        kind: 'publish',
-        status: 'in_progress',
-        displayName: 'Publishing…'
-      })
-    ]);
-    expect(steps[1].status).toBe('pending');
-    expect(steps[1].blockedBy).toEqual<PublishStepKind[]>(['policy_gates']);
-    expect(steps[1].displayName).toBe('Publish');
-  });
-
-  test('clears blockedBy when all earlier steps are clear', () => {
-    const steps = applyBlockedByEligibility([
-      step({ id: 'build', kind: 'build', status: 'passed' }),
-      step({ id: 'publish', kind: 'publish', status: 'pending', blockedBy: ['build'] })
-    ]);
-    expect(steps[1].blockedBy).toBeUndefined();
-  });
-
-  test('does not block policy gates on an unfinished build (they run concurrently)', () => {
-    const steps = applyBlockedByEligibility([
-      step({ id: 'build', kind: 'build', status: 'in_progress' }),
-      step({
-        id: 'policy_gates:before_deploy',
-        kind: 'policy_gates',
-        status: 'in_progress',
-        displayName: 'Pre-Publish Policies'
-      })
-    ]);
-    expect(steps[1].blockedBy).toBeUndefined();
-    expect(steps[1].status).toBe('in_progress');
-    expect(steps[1].displayName).toBe('Pre-Publish Policies');
-  });
-
-  test('keeps a pending policy gate idle rather than waiting on the build', () => {
-    const steps = applyBlockedByEligibility([
-      step({ id: 'build', kind: 'build', status: 'in_progress' }),
-      step({ id: 'policy_gates:before_deploy', kind: 'policy_gates', status: 'pending' })
-    ]);
-    expect(steps[1].blockedBy).toBeUndefined();
-    expect(steps[1].status).toBe('pending');
-  });
-
-  test('still blocks publish on both the build and policy gates', () => {
-    const steps = applyBlockedByEligibility([
-      step({ id: 'build', kind: 'build', status: 'in_progress' }),
-      step({ id: 'policy_gates:before_deploy', kind: 'policy_gates', status: 'in_progress' }),
-      step({ id: 'publish', kind: 'publish', status: 'pending' })
-    ]);
-    expect(steps[2].blockedBy).toEqual<PublishStepKind[]>(['build', 'policy_gates']);
-    expect(steps[2].status).toBe('pending');
-  });
-
-  test('lists each unclear kind at most once in blockedBy', () => {
-    // Two earlier steps can share a kind (e.g. multiple database_* rows). The
-    // rail waits on kinds, not step ids, so blockedBy must not repeat a kind.
-    const steps = applyBlockedByEligibility([
-      step({
-        id: 'database_provisioning:a',
-        kind: 'database_provisioning',
-        status: 'in_progress'
-      }),
-      step({
-        id: 'database_provisioning:b',
-        kind: 'database_provisioning',
-        status: 'pending'
-      }),
-      step({ id: 'publish', kind: 'publish', status: 'pending' })
-    ]);
-    expect(steps[2].blockedBy).toEqual<PublishStepKind[]>(['database_provisioning']);
-  });
-});
-
 describe('buildPublishPlan', () => {
-  test('orders, applies eligibility, and rolls up', () => {
+  test('orders steps on the spine and rolls up without inferring blockedBy', () => {
     const plan = buildPublishPlan(TARGET, [
-      step({ id: 'publish', kind: 'publish', status: 'pending' }),
+      step({ id: 'publish', kind: 'publish', status: 'pending', blockedBy: ['build'] }),
       step({ id: 'build', kind: 'build', status: 'in_progress' })
     ]);
     expect(plan.target).toEqual(TARGET);
@@ -194,6 +93,14 @@ describe('buildPublishPlan', () => {
     expect(plan.status).toBe('in_progress');
   });
 
+  test('leaves a pending later step unblocked when blockedBy was not set', () => {
+    const plan = buildPublishPlan(TARGET, [
+      step({ id: 'publish', kind: 'publish', status: 'pending' }),
+      step({ id: 'build', kind: 'build', status: 'in_progress' })
+    ]);
+    expect(plan.steps[1].blockedBy).toBeUndefined();
+  });
+
   test('an empty plan is passed', () => {
     expect(buildPublishPlan(TARGET, []).status).toBe('passed');
   });

package/src/types/publishPipeline/plan.ts

@@ -1,5 +1,4 @@
-import { publishStepDisplayName } from './displayNames.js';
-import type { PublishPlan, PublishPlanTarget, PublishStep, PublishStepKind, PublishStepStatus } from './index.js';
+import type { PublishPlan, PublishPlanTarget, PublishStep, PublishStepStatus } from './index.js';
 import { PUBLISH_STEP_SPINE } from './index.js';
 
 /** Worst-first. When summarizing many steps into one status, first match wins. */
@@ -15,8 +14,6 @@ const STATUS_PRECEDENCE: PublishStepStatus[] = [
   'skipped'
 ];
 
-const CLEAR_STATUSES = new Set<PublishStepStatus>(['passed', 'advisory', 'skipped']);
-
 /** Collapse ordered steps into the single status shown on the plan. Empty = passed. */
 export function rollUpPublishPlan(steps: PublishStep[]): PublishStepStatus {
   const present = new Set(steps.map((s) => s.status));
@@ -43,64 +40,8 @@ export function orderPublishSteps(steps: PublishStep[]): PublishStep[] {
   return ordered;
 }
 
-function isClear(status: PublishStepStatus): boolean {
-  return CLEAR_STATUSES.has(status);
-}
-
-/**
- * Kinds that execute concurrently and therefore must not appear as each other's
- * prerequisite. The SABS build and the policy agents both key off the commit and
- * run in parallel — policy agents analyze the committed code directly and do not
- * wait for the build artifact — so neither should show "Waiting on" the other in
- * the rail. They both still gate the final publish.
- */
-const CONCURRENT_KINDS = new Set<PublishStepKind>(['build', 'policy_gates']);
-
-/** An earlier unclear step gates a later step unless the two run concurrently. */
-function earlierKindBlocks(earlier: PublishStepKind, current: PublishStepKind): boolean {
-  return !(CONCURRENT_KINDS.has(earlier) && CONCURRENT_KINDS.has(current));
-}
-
-/**
- * For each step that is not yet clear, set `blockedBy` to kinds of earlier
- * steps that are not clear and that actually gate it (concurrent steps such as
- * build and policy gates do not gate each other). Premature `in_progress` (e.g.
- * deploy already QUEUED while policy gates still run) is held as `pending` so
- * the rail does not show "Publishing…" ahead of unfinished prerequisites. Failed
- * and other terminal statuses are left alone. Clears blockedBy when the gating
- * steps clear.
- */
-export function applyBlockedByEligibility(steps: PublishStep[]): PublishStep[] {
-  // Kind set (not a list): multiple earlier steps can share a kind, but the
-  // rail waits on kinds — blockedBy must not repeat the same kind.
-  const unclearKinds = new Set<PublishStepKind>();
-  return steps.map((step) => {
-    const blockers = [...unclearKinds].filter((kind) => earlierKindBlocks(kind, step.kind));
-    if (blockers.length > 0 && (step.status === 'pending' || step.status === 'in_progress')) {
-      const next: PublishStep = {
-        ...step,
-        status: 'pending',
-        blockedBy: blockers,
-        displayName: publishStepDisplayName(step.kind, 'pending')
-      };
-      unclearKinds.add(step.kind);
-      return next;
-    }
-    if (step.status === 'pending') {
-      const rest = { ...step };
-      delete rest.blockedBy;
-      unclearKinds.add(step.kind);
-      return rest;
-    }
-    if (!isClear(step.status)) {
-      unclearKinds.add(step.kind);
-    }
-    return step;
-  });
-}
-
-/** Order, apply eligibility, roll up. */
+/** Order and roll up. Assemble resolves each step's declared `blockedBy`. */
 export function buildPublishPlan(target: PublishPlanTarget, steps: PublishStep[]): PublishPlan {
-  const ordered = applyBlockedByEligibility(orderPublishSteps(steps));
+  const ordered = orderPublishSteps(steps);
   return { status: rollUpPublishPlan(ordered), steps: ordered, target };
 }

package/src/types/response/PostApplicationCloneResponseBody.ts

@@ -0,0 +1,12 @@
+import type { IApplicationV2Dto } from '../application/index.js';
+
+export type PostApplicationCloneResponseBody = IApplicationV2Dto & {
+  /**
+   * True when the source app had a managed database. Cloning copies the source
+   * code but not the database, its migration requirement or its integration, so
+   * the clone's code still points at the source app's integration id and cannot
+   * reach a database of its own until one is provisioned and the code is
+   * repointed. The editor uses this to start that setup on first open.
+   */
+  requiresDatabaseSetup?: boolean;
+};

package/src/types/response/index.ts

@@ -15,6 +15,7 @@ export * from './PostApplicationCommitCreateResponseBody.js';
 export * from './PostApiBranchCreateResponseBody.js';
 export * from './PostApplicationBranchCreateResponseBody.js';
 export * from './PostApplicationRemoteCommitCreateResponseBody.js';
+export * from './PostApplicationCloneResponseBody.js';
 export * from './PostApplicationCreateResponseBody.js';
 export * from './PostApplicationDeployResponseBody.js';
 export * from './PostApplicationResetResponseBody.js';

package/src/types/reviewPolicy/index.ts

@@ -22,7 +22,8 @@ export const REVIEW_POLICY_EXECUTION_CONTEXTS = [
   'superblocks_sabs_source_snapshot'
 ] as const;
 export const REVIEW_POLICY_RUNTIMES = ['superblocks_dev_server_agent', 'superblocks_sabs'] as const;
-export const REVIEW_POLICY_MODES = ['advisory', 'blocking'] as const;
+// Ordered from least to most strict; the mode select renders in array order.
+export const REVIEW_POLICY_MODES = ['advisory', 'blocking_with_exceptions', 'blocking'] as const;
 export const REVIEW_POLICY_RUNNER_TYPES = ['built_in_security_scan', 'llm_security_agent'] as const;
 export const REVIEW_FINDING_SOURCE_PHASES = ['built_asset', 'dependency', 'edit_mode_app', 'iac', 'image', 'source'] as const;
 export const REVIEW_FINDING_CATEGORIES = [
@@ -190,6 +191,11 @@ export interface ReviewFindingDto {
   humanSummary: string | null;
   technicalSummary: string | null;
   evidence: Record<string, unknown>;
+  /**
+   * Scanner-specific location payloads; the primary location (where the rule
+   * fired) MUST be first. Known shapes: `{ filePath, line }` (security agent),
+   * `{ filePath, startLine, endLine }` (semgrep), `{ path | file, line }` (legacy).
+   */
   locations: unknown[];
   remediationHint: Record<string, unknown>;
   clarkRemediable: boolean;

package/src/utils/attachment-upload.test.ts

@@ -1,10 +1,12 @@
 import { describe, expect, test } from 'vitest';
 
 import {
+  ATTACHMENT_CONTENT_MISMATCH_CODE,
   buildAttachmentUploadMetadata,
   buildAttachmentUploadFormData,
   createUploadedAttachmentFromServer,
   getTextAttachmentType,
+  parseUserFacingUploadError,
   isOfficeXml,
   normalizeAttachmentMimeType,
   toAttachmentUploadDescriptor
@@ -74,7 +76,10 @@ describe('buildAttachmentUploadFormData', () => {
 
     const uploadedFile = formData.get('file');
     expect(uploadedFile).toBeInstanceOf(File);
-    expect((uploadedFile as File).name).toBe('capture.webp');
+    if (!(uploadedFile instanceof File)) {
+      throw new Error('expected File');
+    }
+    expect(uploadedFile.name).toBe('capture.webp');
     expect(formData.get('prefix')).toBe('captured-screenshot');
   });
 
@@ -255,3 +260,45 @@ describe('isOfficeXml', () => {
     ).toBe(false);
   });
 });
+
+// The server returns a user-facing sentence in `{ error }` for actionable
+// rejections. Wrapping it in `status=400, body={...}` buries the only part
+// the user can act on inside a developer-shaped string.
+describe('parseUserFacingUploadError', () => {
+  test('extracts the server error sentence', () => {
+    const body = JSON.stringify({
+      code: ATTACHMENT_CONTENT_MISMATCH_CODE,
+      error: 'inspection_256551628.pdf is not a valid PDF. The file may be corrupted or saved with the wrong extension.'
+    });
+    expect(parseUserFacingUploadError(body)).toEqual({
+      code: ATTACHMENT_CONTENT_MISMATCH_CODE,
+      message: 'inspection_256551628.pdf is not a valid PDF. The file may be corrupted or saved with the wrong extension.'
+    });
+  });
+
+  // `{ error }` is the upload route's generic error channel, used for internal
+  // 500/502 diagnostics too ('App scoped token is required...', 'Bucketeer
+  // returned an invalid response', and raw Bucketeer response text). Without a
+  // discriminator, promoting it verbatim showed users internal upstream detail
+  // as if it were actionable guidance.
+  test.each([
+    ['no code at all', { error: 'Bucketeer returned an invalid response' }],
+    ['an unknown code', { code: 'internal_upstream_failure', error: '<stack trace and host detail>' }],
+    ['a non-string code', { code: 42, error: 'App scoped token is required for app scope uploads' }]
+  ])('does not promote a server error carrying %s', (_label, body) => {
+    expect(parseUserFacingUploadError(JSON.stringify(body))).toBeUndefined();
+  });
+
+  test.each([
+    ['non-JSON body', '<html>502 Bad Gateway</html>'],
+    ['empty body', ''],
+    ['whitespace body', '   '],
+    ['JSON without an error field', '{"message":"nope"}'],
+    ['JSON with a non-string error', '{"error":{"code":42}}'],
+    ['JSON with a blank error', '{"error":"   "}'],
+    ['JSON array', '[1,2,3]'],
+    ['JSON null', 'null']
+  ])('returns undefined for %s so the caller keeps the diagnostic form', (_label, body) => {
+    expect(parseUserFacingUploadError(body)).toBeUndefined();
+  });
+});

package/src/utils/attachment-upload.ts

@@ -630,8 +630,86 @@ export async function uploadAttachmentToServerApi(params: {
 
   if (!response.ok) {
     const errorText = await response.text().catch(() => '');
+    const parsed = parseUserFacingUploadError(errorText);
+    if (parsed) {
+      throw new AttachmentUploadApiError(parsed.message, {
+        code: parsed.code,
+        status: response.status
+      });
+    }
     throw new Error(`Attachment upload failed: status=${response.status}${errorText ? `, body=${errorText}` : ''}`);
   }
 
   return (await response.json()) as AttachmentUploadServerDto;
 }
+
+/**
+ * The upload route sets this code ONLY on rejections whose `{ error }` sentence
+ * is written for the end user and is safe to show verbatim.
+ *
+ * `{ error }` is otherwise the route's generic diagnostic channel. It carries
+ * internal 500/502 detail (app-scoped-token, invalid Bucketeer response, raw
+ * Bucketeer text). Promoting that to a user-facing sentence leaked upstream
+ * internals into the UI, so the verbatim path is gated on this code rather
+ * than on the presence of the field.
+ */
+export type UserFacingUploadErrorCode = 'attachment_content_mismatch';
+
+export const ATTACHMENT_CONTENT_MISMATCH_CODE: UserFacingUploadErrorCode = 'attachment_content_mismatch';
+
+export class AttachmentUploadApiError extends Error {
+  readonly code: UserFacingUploadErrorCode;
+  readonly status: number;
+
+  constructor(message: string, options: { code: UserFacingUploadErrorCode; status: number }) {
+    super(message);
+    this.name = 'AttachmentUploadApiError';
+    this.code = options.code;
+    this.status = options.status;
+  }
+}
+
+export function isUserFacingUploadError(error: unknown): error is AttachmentUploadApiError {
+  return error instanceof AttachmentUploadApiError;
+}
+
+function readStringProperty(value: object, key: string): string | undefined {
+  if (!(key in value)) {
+    return undefined;
+  }
+  const property = Reflect.get(value, key);
+  return typeof property === 'string' ? property : undefined;
+}
+
+function isUserFacingUploadErrorCode(code: string): code is UserFacingUploadErrorCode {
+  return code === ATTACHMENT_CONTENT_MISMATCH_CODE;
+}
+
+/**
+ * Pull the server's user-facing `{ code, error }` pair out of a response body.
+ * Returns undefined unless `code` is {@link ATTACHMENT_CONTENT_MISMATCH_CODE},
+ * and for non-JSON bodies, non-string `error` fields, and blank strings, so
+ * the caller keeps the diagnostic form that still carries the HTTP status.
+ */
+export function parseUserFacingUploadError(body: string): { code: UserFacingUploadErrorCode; message: string } | undefined {
+  if (!body.trim()) {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (typeof parsed !== 'object' || parsed === null) {
+      return undefined;
+    }
+    const code = readStringProperty(parsed, 'code');
+    const message = readStringProperty(parsed, 'error');
+    if (code === undefined || !isUserFacingUploadErrorCode(code)) {
+      return undefined;
+    }
+    if (message === undefined || !message.trim()) {
+      return undefined;
+    }
+    return { code, message };
+  } catch {
+    return undefined;
+  }
+}

package/src/utils/git-url.test.ts

@@ -21,6 +21,10 @@ describe('isValidGitUrl', () => {
   it('trims whitespace', () => {
     expect(isValidGitUrl('  https://github.com/org/repo  ')).toBe(true);
   });
+
+  it('accepts ssh:// double-slash absolute-path URLs (valid git SSH syntax)', () => {
+    expect(isValidGitUrl('ssh://git@host//org/repo.git')).toBe(true);
+  });
 });
 
 describe('isGitHubUrl', () => {
@@ -144,3 +148,64 @@ describe('sshGitUrlToHttps', () => {
     expect(sshGitUrlToHttps('not-a-url')).toBeNull();
   });
 });
+
+describe('git-url ReDoS (SEC-78)', () => {
+  it('still validates/normalizes real URLs', () => {
+    expect(isValidGitUrl('https://github.com/org/repo.git')).toBe(true);
+    expect(isValidGitUrl('git@github.com:org/repo.git')).toBe(true);
+    expect(isValidGitUrl('ssh://git@github.com/org/repo')).toBe(true);
+    expect(isValidGitUrl('not a url')).toBe(false);
+    expect(gitRemoteUrlToWeb('git@github.com:org/repo.git')).toBe('https://github.com/org/repo');
+    expect(sshGitUrlToHttps('git@github.com:org/repo.git')).toBe('https://github.com/org/repo.git');
+  });
+
+  it('still converts SCP-style paths containing spaces (e.g. Azure DevOps repo names)', () => {
+    // Raw SCP `git@host:path` strings are not URL-encoded by convention, so
+    // legitimate paths (Azure DevOps project/repo names in particular) may
+    // contain literal spaces. The bounded regex must preserve this — only the
+    // length is capped, not the character class.
+    expect(gitRemoteUrlToWeb('git@host:org/repo name.git')).toBe('https://host/org/repo name');
+    expect(sshGitUrlToHttps('git@host:org/repo name.git')).toBe('https://host/org/repo name.git');
+  });
+
+  it('does not rescan trailing whitespace polynomially on the SCP sshMatch fallback', () => {
+    // Internal-whitespace shape: a long run of spaces BEFORE the final
+    // non-whitespace char, rather than after it (the existing adversarial
+    // test puts the non-whitespace run first). Against the pre-fix
+    // `(?:\.git)?\s*$` tail this drove a genuine O(4096*n) scan (measured
+    // ~3.9s at n=1,000,000) because the lazy path capture and the trailing
+    // `\s*` were two independent backtracking axes. `trimmed` never ends in
+    // whitespace, so `\s*` before the final `$` was always redundant — it
+    // was dropped in favor of a plain `$`.
+    const evil = 'git@h:' + ' '.repeat(200000) + 'X';
+    const start = performance.now();
+    gitRemoteUrlToWeb(evil);
+    sshGitUrlToHttps(evil);
+    expect(performance.now() - start).toBeLessThan(100);
+  });
+
+  it('does not backtrack polynomially on adversarial inputs', () => {
+    const cases = [
+      'https://' + 'a.'.repeat(50000), // HTTPS_GIT_URL_RE host
+      'https://x/' + 'a/'.repeat(50000), // HTTPS_GIT_URL_RE path
+      'git@' + 'a.'.repeat(50000) + ':x', // SSH_GIT_URL_RE host
+      'ssh://git@h/' + 'a/'.repeat(50000), // SSH_PROTOCOL_RE path
+      'git@h:' + 'a'.repeat(200000), // SCP sshMatch (L72/226)
+      // Trailing-whitespace ambiguity against the `(?:\.git)?\s*$` tail: the
+      // lazy `.+?` capture and the `\s*` quantifier are two independent
+      // O(n) backtracking axes, which combine into genuine O(n^2) blowup on
+      // the pre-fix regex (confirmed: ~35ms at n=8000, ~120ms at n=16000 —
+      // consistent ~4x-per-2x quadratic scaling; would take tens of seconds
+      // at n=200000 without the bound).
+      'git@h:' + 'a'.repeat(16000) + ' '.repeat(16000) + 'X',
+      'git@ssh.dev.azure.com:v3/o/p/' + 'a'.repeat(16000) + ' '.repeat(16000) + 'X'
+    ];
+    for (const evil of cases) {
+      const start = performance.now();
+      isValidGitUrl(evil);
+      gitRemoteUrlToWeb(evil);
+      sshGitUrlToHttps(evil);
+      expect(performance.now() - start).toBeLessThan(150);
+    }
+  });
+});