@superblocksteam/shared 0.9613.2 → 0.9614.1

package/src/types/policyGate/index.ts

@@ -1,4 +1,9 @@
-import type { ReviewFindingCategory, ReviewFindingConfidence, ReviewFindingSeverity } from '../reviewPolicy/index.js';
+import type {
+  ReviewFindingCategory,
+  ReviewFindingConfidence,
+  ReviewFindingSeverity,
+  ReviewPolicyRunnerType
+} from '../reviewPolicy/index.js';
 import { MAX_POLICY_GATE_RUN_ATTEMPTS } from './errors.js';
 
 export * from './errors.js';
@@ -31,6 +36,8 @@ export type PolicyGateReadinessFindingSummary = {
 export type PolicyGateReadinessFinding = {
   blocking: boolean;
   humanSummary?: string | null;
+  /** Stable id for the underlying finding row; prefer this over hashing display text for identity. */
+  id?: string;
   /** Same contract as `ReviewFindingDto.locations`: primary location first. */
   locationsJson?: unknown[];
   remediationHintJson?: Record<string, unknown>;
@@ -69,6 +76,7 @@ export type PolicyGateReadinessItem = {
   policyVersionId: string;
   progress?: PolicyGateScanProgress;
   reviewRunId?: string;
+  runnerType?: ReviewPolicyRunnerType;
   runs?: PolicyGateReadinessRun[];
   staleReason?: string;
   status: PolicyGateReadinessItemStatus;
@@ -181,6 +189,18 @@ export type ScanScopeChangedFile = {
   path: string;
 };
 
+// Git-connected and imported apps can still carry pnpm, yarn, or bun lockfiles. A package
+// manager regenerating one (different resolved order, no real edit) should not by itself
+// count as a code change for scan-scope purposes. Shared between the server (which builds
+// ScanScopeJson) and the dev-server agent (which consumes it) so the two never drift.
+const LOCKFILE_BASENAMES = new Set(['bun.lock', 'bun.lockb', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock']);
+
+export function isLockfilePath(path: string): boolean {
+  const lastSlashIndex = path.lastIndexOf('/');
+  const basename = lastSlashIndex === -1 ? path : path.slice(lastSlashIndex + 1);
+  return LOCKFILE_BASENAMES.has(basename);
+}
+
 export type ScanScopePriorFinding = {
   blocking: boolean;
   category: ReviewFindingCategory;

package/src/types/publishPipeline/index.ts

@@ -10,6 +10,8 @@
  * this plan only reflects progress for the rail.
  */
 
+import type { PolicyGateReadinessStatus } from '../policyGate/index.js';
+
 /** Which domain owns a step. Extend as new gates are added. */
 export type PublishStepKind = 'build' | 'database_migration' | 'database_provisioning' | 'policy_gates' | 'publish';
 
@@ -35,6 +37,23 @@ export type BuildPublishStepDetail = {
   error?: string;
 };
 
+export type PolicyGatesPublishStepDetail = {
+  /**
+   * Whether the server would honor a publish that carries the findings
+   * acknowledgment right now. False while a gate has not reported: its findings
+   * are part of what the acknowledgment covers, so the deploy endpoint applies
+   * this same test and turns such a publish away. Also false when the gates
+   * could not be read at all - an unknown answer must not offer a publish that
+   * would come back refused.
+   *
+   * Separate from whether anyone has acknowledged anything: that is recorded on
+   * the deploy queue row and is already visible in each child's status.
+   */
+  findingsAckEligible: boolean;
+  /** Absent when readiness could not be read. */
+  readinessStatus?: PolicyGateReadinessStatus;
+};
+
 export type PublishDeployStepDetail = {
   error?: string;
   isLive?: boolean;
@@ -54,6 +73,8 @@ export type PublishStep = {
   summary?: string;
   /** When status is pending and waiting on declared dependencies that are not yet clear. */
   blockedBy?: PublishStepKind[];
+  /** Nested status rows owned by this step. */
+  children?: PublishStep[];
   /** Machine code when blocked/failed (e.g. POLICY_GATE_BLOCKED). */
   blockingReason?: string;
   /** Opaque domain payload; generic pipeline must not read this. */
@@ -66,6 +87,13 @@ export type PublishPlanTarget = {
 };
 
 export type PublishPlan = {
+  /**
+   * Whether publishing this app runs policy agents, as the organization has it
+   * configured. Unlike the steps, this does not describe one version: the steps
+   * only appear once a publish of that version is under way, while an older
+   * version needs to know the checks exist before anyone tries.
+   */
+  hasPolicyPublishChecks?: boolean;
   status: PublishStepStatus;
   steps: PublishStep[];
   target: PublishPlanTarget;
@@ -103,3 +131,4 @@ export const PUBLISH_STEP_SPINE: readonly PublishStepId[] = [
 
 export * from './displayNames.js';
 export * from './plan.js';
+export * from './policyStatus.js';

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

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'vitest';
 
 import type { PublishStep, PublishStepStatus } from './index.js';
-import { buildPublishPlan, orderPublishSteps, rollUpPublishPlan } from './plan.js';
+import { buildPublishPlan, orderPublishSteps, rollUpPublishSteps } from './plan.js';
 
 const TARGET = { applicationId: 'app-1', commitId: 'commit-1' };
 
@@ -14,22 +14,26 @@ function step(overrides: Partial<PublishStep> & Pick<PublishStep, 'id'>): Publis
   };
 }
 
-describe('rollUpPublishPlan', () => {
+describe('rollUpPublishSteps', () => {
   test('an empty plan is passed', () => {
-    expect(rollUpPublishPlan([])).toBe('passed');
+    expect(rollUpPublishSteps([])).toBe('passed');
   });
 
   test('the worst status wins by precedence', () => {
     expect(
-      rollUpPublishPlan([step({ id: 'a', status: 'passed' }), step({ id: 'b', status: 'advisory' }), step({ id: 'c', status: 'blocked' })])
+      rollUpPublishSteps([step({ id: 'a', status: 'passed' }), step({ id: 'b', status: 'advisory' }), step({ id: 'c', status: 'blocked' })])
     ).toBe('blocked');
-    expect(rollUpPublishPlan([step({ id: 'a', status: 'in_progress' }), step({ id: 'b', status: 'failed' })])).toBe('failed');
-    expect(rollUpPublishPlan([step({ id: 'a', status: 'advisory' }), step({ id: 'b', status: 'passed' })])).toBe('advisory');
+    expect(rollUpPublishSteps([step({ id: 'a', status: 'in_progress' }), step({ id: 'b', status: 'failed' })])).toBe('failed');
+    expect(rollUpPublishSteps([step({ id: 'a', status: 'advisory' }), step({ id: 'b', status: 'passed' })])).toBe('advisory');
   });
 
   test('skipped never masks a real status', () => {
-    expect(rollUpPublishPlan([step({ id: 'a', status: 'skipped' }), step({ id: 'b', status: 'passed' })])).toBe('passed');
-    expect(rollUpPublishPlan([step({ id: 'a', status: 'skipped' })])).toBe('skipped');
+    expect(rollUpPublishSteps([step({ id: 'a', status: 'skipped' }), step({ id: 'b', status: 'passed' })])).toBe('passed');
+    expect(rollUpPublishSteps([step({ id: 'a', status: 'skipped' })])).toBe('skipped');
+  });
+
+  test('an unknown wire status blocks the plan', () => {
+    expect(rollUpPublishSteps([step({ id: 'new-server-status', status: 'new_server_status' as PublishStepStatus })])).toBe('blocked');
   });
 
   test('precedence order is exhaustive and worst-first', () => {
@@ -50,9 +54,30 @@ describe('rollUpPublishPlan', () => {
       const steps = better
         ? [step({ id: 'better', status: better }), step({ id: 'worse', status: worse })]
         : [step({ id: 'only', status: worse })];
-      expect(rollUpPublishPlan(steps)).toBe(worse);
+      expect(rollUpPublishSteps(steps)).toBe(worse);
     }
   });
+
+  test('uses the plan precedence for any sibling steps', () => {
+    const children = [
+      step({ id: 'blocked-child', kind: 'policy_gates', status: 'blocked' }),
+      step({ id: 'running-child', kind: 'policy_gates', status: 'in_progress' })
+    ];
+
+    expect(rollUpPublishSteps(children)).toBe('blocked');
+    expect(rollUpPublishSteps([step({ id: 'pending-child', status: 'pending' }), step({ id: 'passed-child' })])).toBe('pending');
+  });
+
+  test('reads sibling statuses without reinterpreting nested children', () => {
+    const parent = step({
+      children: [step({ id: 'policy:security-agent', kind: 'policy_gates', status: 'failed' })],
+      id: 'policy_gates:before_deploy',
+      kind: 'policy_gates',
+      status: 'passed'
+    });
+
+    expect(rollUpPublishSteps([parent])).toBe('passed');
+  });
 });
 
 describe('orderPublishSteps', () => {

package/src/types/publishPipeline/plan.ts

@@ -1,23 +1,36 @@
 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. */
-const STATUS_PRECEDENCE: PublishStepStatus[] = [
-  'failed',
-  'blocked',
-  'action_required',
-  'stale',
-  'in_progress',
-  'pending',
-  'advisory',
-  'passed',
-  'skipped'
-];
+/** Lower ranks are worse so every known status has an explicit precedence. */
+const STATUS_RANK: Record<PublishStepStatus, number> = {
+  failed: 0,
+  blocked: 1,
+  action_required: 2,
+  stale: 3,
+  in_progress: 4,
+  pending: 5,
+  advisory: 6,
+  passed: 7,
+  skipped: 8
+};
 
-/** 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));
-  return STATUS_PRECEDENCE.find((s) => present.has(s)) ?? 'passed';
+/** Collapse sibling steps into one status. Empty = passed. */
+export function rollUpPublishSteps(steps: Pick<PublishStep, 'status'>[]): PublishStepStatus {
+  if (steps.length === 0) {
+    return 'passed';
+  }
+
+  let worst: PublishStepStatus = 'skipped';
+  for (const step of steps) {
+    const rank = STATUS_RANK[step.status];
+    if (rank === undefined) {
+      return 'blocked';
+    }
+    if (rank < STATUS_RANK[worst]) {
+      worst = step.status;
+    }
+  }
+  return worst;
 }
 
 /** Order steps by the fixed spine; unknown ids are appended in input order. */
@@ -40,8 +53,17 @@ export function orderPublishSteps(steps: PublishStep[]): PublishStep[] {
   return ordered;
 }
 
-/** Order and roll up. Assemble resolves each step's declared `blockedBy`. */
-export function buildPublishPlan(target: PublishPlanTarget, steps: PublishStep[]): PublishPlan {
+/**
+ * Order and roll up. Assemble resolves each step's declared `blockedBy`.
+ *
+ * `facts` carries what the plan says about the app rather than about its steps,
+ * so rebuilding a plan from a response keeps it instead of dropping it.
+ */
+export function buildPublishPlan(
+  target: PublishPlanTarget,
+  steps: PublishStep[],
+  facts?: Pick<PublishPlan, 'hasPolicyPublishChecks'>
+): PublishPlan {
   const ordered = orderPublishSteps(steps);
-  return { status: rollUpPublishPlan(ordered), steps: ordered, target };
+  return { ...facts, status: rollUpPublishSteps(ordered), steps: ordered, target };
 }

package/src/types/publishPipeline/policyStatus.ts

@@ -0,0 +1,44 @@
+import { isHardBlockingPolicyItem, isPublishHoldingPolicyItem, type PolicyGateReadinessItem } from '../policyGate/index.js';
+import { isAdvisoryHoldFindingSeverity } from '../reviewPolicy/index.js';
+import type { PublishStepStatus } from './index.js';
+
+export function policyItemPublishStatus(
+  item: PolicyGateReadinessItem,
+  options: {
+    blockingHoldAcknowledged?: boolean;
+    blockingHoldAckEligible?: boolean;
+  } = {}
+): PublishStepStatus {
+  const { blockingHoldAcknowledged = false, blockingHoldAckEligible = false } = options;
+  switch (item.status) {
+    case 'failed':
+      if (isPublishHoldingPolicyItem(item)) {
+        return blockingHoldAcknowledged && blockingHoldAckEligible ? 'advisory' : 'blocked';
+      }
+      return isHardBlockingPolicyItem(item) ? 'failed' : 'advisory';
+    case 'blocked':
+      if (isHardBlockingPolicyItem(item)) {
+        return 'blocked';
+      }
+      if (isPublishHoldingPolicyItem(item)) {
+        return blockingHoldAcknowledged && blockingHoldAckEligible ? 'advisory' : 'blocked';
+      }
+      return 'advisory';
+    case 'approval_required':
+      return 'action_required';
+    case 'stale':
+      return 'stale';
+    case 'running':
+      return 'in_progress';
+    case 'missing':
+      return 'pending';
+    case 'advisory_findings':
+      return (item.findings ?? []).some((finding) => isAdvisoryHoldFindingSeverity(finding.severity)) ? 'advisory' : 'passed';
+    case 'passed':
+      return 'passed';
+    default: {
+      const _exhaustive: never = item.status;
+      return _exhaustive;
+    }
+  }
+}

package/src/types/reviewPolicy/index.ts

@@ -12,19 +12,26 @@ export const BUILT_IN_SECURITY_SCAN_NAME = 'Superblocks Security Scan';
 // by the platform, so admins can only enable it and choose its mode.
 export const SUPERBLOCKS_SECURITY_AGENT_NAME = 'Superblocks Security Agent';
 
-export const REVIEW_POLICY_TYPES = ['built_in_security_scan', 'security_agent'] as const;
+// Display name of the Superblocks-managed pre-publish dependency CVE check. One per organization;
+// runs synchronously against the vulnerability index, so it needs no runner config to enable.
+export const DEPENDENCY_VULNERABILITY_SCAN_NAME = 'Superblocks Vulnerability Detection';
+
+export const REVIEW_POLICY_TYPES = ['built_in_security_scan', 'security_agent', 'dependency_vulnerability_scan'] as const;
 export const REVIEW_POLICY_SOURCES = ['admin_configured', 'superblocks_managed'] as const;
 export const REVIEW_POLICY_TRIGGERS = ['before_deploy', 'after_checkpoint', 'manual'] as const;
 export const REVIEW_POLICY_EXECUTION_CONTEXTS = [
   'edit_mode_app',
   'superblocks_sabs_built_assets',
   'superblocks_sabs_dependency_metadata',
-  'superblocks_sabs_source_snapshot'
+  'superblocks_sabs_source_snapshot',
+  'dependency_manifest'
 ] as const;
-export const REVIEW_POLICY_RUNTIMES = ['superblocks_dev_server_agent', 'superblocks_sabs'] as const;
+// `superblocks_server` runs in-process on the API server (no external runner), for checks like the
+// dependency vulnerability scan that only need data already indexed at commit time.
+export const REVIEW_POLICY_RUNTIMES = ['superblocks_dev_server_agent', 'superblocks_sabs', 'superblocks_server'] 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_POLICY_RUNNER_TYPES = ['built_in_security_scan', 'llm_security_agent', 'dependency_vulnerability_scan'] as const;
 export const REVIEW_FINDING_SOURCE_PHASES = ['built_asset', 'dependency', 'edit_mode_app', 'iac', 'image', 'source'] as const;
 export const REVIEW_FINDING_CATEGORIES = [
   'external_policy',
@@ -262,6 +269,7 @@ export interface ReviewPolicySummaryDto {
 
 export type CreateReviewPolicyBody =
   | { policyType: 'built_in_security_scan'; mode?: ReviewPolicyMode; scope?: ReviewPolicyScopeInput }
+  | { policyType: 'dependency_vulnerability_scan'; mode?: ReviewPolicyMode; scope?: ReviewPolicyScopeInput }
   | {
       policyType: 'security_agent';
       source: 'superblocks_managed';
@@ -284,6 +292,12 @@ export type UpdateReviewPolicyConfigBody =
       mode: ReviewPolicyMode;
       scope?: ReviewPolicyScopeInput;
     }
+  | {
+      activeVersionId: string;
+      policyType: 'dependency_vulnerability_scan';
+      mode: ReviewPolicyMode;
+      scope?: ReviewPolicyScopeInput;
+    }
   | {
       activeVersionId: string;
       policyType: 'security_agent';

package/src/types/scim/index.ts

@@ -4,9 +4,36 @@ export enum ScimSchema {
   USER_ENTERPRISE = 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User',
   LIST = 'urn:ietf:params:scim:api:messages:2.0:ListResponse',
   PATCH = 'urn:ietf:params:scim:api:messages:2.0:PatchOp',
-  GROUP = 'urn:ietf:params:scim:schemas:core:2.0:Group'
+  GROUP = 'urn:ietf:params:scim:schemas:core:2.0:Group',
+  ERROR = 'urn:ietf:params:scim:api:messages:2.0:Error'
 }
 
+// RFC 7644 section 3.1: the media type SCIM requests and responses use.
+export const SCIM_CONTENT_TYPE = 'application/scim+json';
+
+// The ten keywords of RFC 7644 Table 9 (section 3.12). An IdP reads this to decide whether a
+// failure is permanent or worth retrying, so a wrong keyword is worse than none.
+export enum ScimErrorType {
+  invalidFilter = 'invalidFilter',
+  tooMany = 'tooMany',
+  uniqueness = 'uniqueness',
+  mutability = 'mutability',
+  invalidSyntax = 'invalidSyntax',
+  invalidPath = 'invalidPath',
+  noTarget = 'noTarget',
+  invalidValue = 'invalidValue',
+  invalidVers = 'invalidVers',
+  sensitive = 'sensitive'
+}
+
+// RFC 7644 section 3.12: `status` is the HTTP status as a string, and `scimType` is optional.
+export type ScimError = {
+  schemas: [ScimSchema.ERROR];
+  status: string;
+  detail: string;
+  scimType?: ScimErrorType;
+};
+
 export enum OperationCode {
   replace = 'replace',
   add = 'add',

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

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'vitest';
+
+import { classifyAttachmentDelivery, isDumpAttachment, isSupportedAttachmentUploadType } from './attachment-delivery.js';
+
+describe('dump attachments', () => {
+  test('detects .dump by filename regardless of mime type', () => {
+    expect(isDumpAttachment({ fileName: 'orders_prod.dump' })).toBe(true);
+    expect(isDumpAttachment({ fileName: 'orders_prod.dump', mimeType: 'application/octet-stream' })).toBe(true);
+    expect(isDumpAttachment({ fileName: 'orders_prod.dump', mimeType: 'text/plain' })).toBe(true);
+    expect(isDumpAttachment({ fileName: 'orders_prod.dump', mimeType: '' })).toBe(true);
+    expect(isDumpAttachment({ fileName: 'orders.sql' })).toBe(false);
+    expect(isDumpAttachment({ fileName: 'archive.zip' })).toBe(false);
+  });
+
+  test('detects dumps by dedicated mime type when filename is missing', () => {
+    expect(isDumpAttachment({ mimeType: 'application/x-postgresql-dump' })).toBe(true);
+    expect(
+      isSupportedAttachmentUploadType({
+        mimeType: 'application/x-postgresql-dump'
+      })
+    ).toBe(true);
+    expect(
+      classifyAttachmentDelivery({
+        mimeType: 'application/x-postgresql-dump'
+      })
+    ).toBe('reference_only');
+  });
+
+  test('classifies dumps as reference-only so they are not inlined to the model', () => {
+    expect(
+      classifyAttachmentDelivery({
+        fileName: 'orders_prod.dump',
+        mimeType: 'application/octet-stream'
+      })
+    ).toBe('reference_only');
+  });
+
+  test('allows dump uploads as a supported attachment type', () => {
+    expect(
+      isSupportedAttachmentUploadType({
+        fileName: 'orders_prod.dump',
+        mimeType: 'application/octet-stream'
+      })
+    ).toBe(true);
+    expect(
+      isSupportedAttachmentUploadType({
+        fileName: 'orders_prod.dump',
+        mimeType: ''
+      })
+    ).toBe(true);
+  });
+});

package/src/utils/attachment-delivery.ts

@@ -61,8 +61,26 @@ export function detectAttachmentArchiveType(input: AttachmentTypeInput): Attachm
   return null;
 }
 
+/**
+ * Postgres custom-format dumps (`pg_dump -Fc`) use the `.dump` extension and are
+ * binary. They must stay reference-only (uploaded to Bucketeer, downloaded via
+ * tool) rather than being coerced to text/plain for the model.
+ */
+export function isDumpAttachment(input: AttachmentTypeInput): boolean {
+  if (normalizeFileName(input.fileName).endsWith('.dump')) {
+    return true;
+  }
+
+  const mimeType = normalizeMimeType(input.mimeType);
+  return mimeType === 'application/x-postgresql-dump' || mimeType === 'application/vnd.postgresql.dump';
+}
+
+export function isReferenceOnlySupportedAttachment(input: AttachmentTypeInput): boolean {
+  return detectAttachmentArchiveType(input) !== null || isDumpAttachment(input);
+}
+
 export function classifyAttachmentDelivery(input: AttachmentTypeInput): AttachmentDeliveryMode {
-  if (detectAttachmentArchiveType(input)) {
+  if (isReferenceOnlySupportedAttachment(input)) {
     return 'reference_only';
   }
 
@@ -84,7 +102,7 @@ export function classifyAttachmentDelivery(input: AttachmentTypeInput): Attachme
 }
 
 export function isSupportedAttachmentUploadType(input: AttachmentTypeInput): boolean {
-  if (detectAttachmentArchiveType(input)) {
+  if (isReferenceOnlySupportedAttachment(input)) {
     return true;
   }
 

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

@@ -1,16 +1,20 @@
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 
 import {
+  ATTACHMENT_INVALID_CODE,
   ATTACHMENT_CONTENT_MISMATCH_CODE,
+  AttachmentUploadApiError,
   buildAttachmentUploadMetadata,
   buildAttachmentUploadFormData,
   createUploadedAttachmentFromServer,
   getAttachmentMimeTypeFromFileName,
   getTextAttachmentType,
-  parseUserFacingUploadError,
   isOfficeXml,
+  isTextLikeMimeType,
   normalizeAttachmentMimeType,
-  toAttachmentUploadDescriptor
+  parseUserFacingUploadError,
+  toAttachmentUploadDescriptor,
+  uploadAttachmentToServerApi
 } from './attachment-upload.js';
 
 describe('getAttachmentMimeTypeFromFileName', () => {
@@ -24,7 +28,8 @@ describe('getAttachmentMimeTypeFromFileName', () => {
     ['report.pdf', 'application/pdf'],
     ['server.log', 'text/plain'],
     ['rows.csv', 'text/csv'],
-    ['config.json', 'application/json']
+    ['config.json', 'application/json'],
+    ['orders_prod.dump', 'application/x-postgresql-dump']
   ])('reads %s as %s', (fileName, expected) => {
     expect(getAttachmentMimeTypeFromFileName(fileName)).toBe(expected);
   });
@@ -183,6 +188,17 @@ describe('buildAttachmentUploadMetadata', () => {
 });
 
 describe('normalizeAttachmentMimeType', () => {
+  test('preserves postgres dump mime types as binary attachments', () => {
+    expect(isTextLikeMimeType('application/x-postgresql-dump')).toBe(false);
+    expect(
+      normalizeAttachmentMimeType({
+        fileName: 'orders_prod.dump',
+        mimeType: 'application/x-postgresql-dump'
+      })
+    ).toBe('application/x-postgresql-dump');
+    expect(normalizeAttachmentMimeType({ mimeType: 'application/vnd.postgresql.dump' })).toBe('application/vnd.postgresql.dump');
+  });
+
   test('prefers text-safe mime types for text-like filenames', () => {
     expect(
       normalizeAttachmentMimeType({
@@ -298,6 +314,14 @@ describe('parseUserFacingUploadError', () => {
     });
   });
 
+  test('extracts attachment validation errors', () => {
+    const body = JSON.stringify({ code: ATTACHMENT_INVALID_CODE, error: 'report.pdf: This file could not be read.' });
+    expect(parseUserFacingUploadError(body)).toEqual({
+      code: ATTACHMENT_INVALID_CODE,
+      message: 'report.pdf: This file could not be read.'
+    });
+  });
+
   // `{ 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
@@ -324,3 +348,33 @@ describe('parseUserFacingUploadError', () => {
     expect(parseUserFacingUploadError(body)).toBeUndefined();
   });
 });
+
+describe('uploadAttachmentToServerApi', () => {
+  test('throws a typed user-facing error for a validation 413', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(
+        new Response(JSON.stringify({ code: ATTACHMENT_INVALID_CODE, error: 'large.txt: This file is too large.' }), { status: 413 })
+      );
+    vi.stubGlobal('fetch', fetchMock);
+    const descriptor = toAttachmentUploadDescriptor(new File(['hello'], 'large.txt', { type: 'text/plain' }));
+    if (!descriptor) throw new Error('expected attachment descriptor');
+
+    await expect(
+      uploadAttachmentToServerApi({
+        authorization: 'Bearer token',
+        baseUrl: 'https://superblocks.example',
+        descriptor,
+        purpose: 'attachment',
+        scopeType: 'org'
+      })
+    ).rejects.toEqual(
+      expect.objectContaining<Partial<AttachmentUploadApiError>>({
+        code: ATTACHMENT_INVALID_CODE,
+        message: 'large.txt: This file is too large.',
+        status: 413
+      })
+    );
+    vi.unstubAllGlobals();
+  });
+});

package/src/utils/attachment-upload.ts

@@ -31,6 +31,8 @@ const TEXT_ATTACHMENT_MIME_TYPES = {
   yaml: 'text/yaml'
 } as const;
 
+const POSTGRES_DUMP_MIME_TYPES = new Set(['application/vnd.postgresql.dump', 'application/x-postgresql-dump']);
+
 export const TEXT_LIKE_FILE_EXTENSIONS = [
   '.txt',
   '.text',
@@ -213,6 +215,10 @@ function normalizeNonEmptyString(value: unknown): string | undefined {
 
 export function isTextLikeMimeType(mimeType: string): boolean {
   const normalizedMimeType = mimeType.toLowerCase();
+  if (POSTGRES_DUMP_MIME_TYPES.has(normalizedMimeType)) {
+    return false;
+  }
+
   return (
     normalizedMimeType.startsWith('text/') ||
     normalizedMimeType.includes('json') ||
@@ -315,6 +321,9 @@ export function getAttachmentMimeTypeFromFileName(fileName?: string): string | u
   if (normalizedFileName.endsWith('.jpeg')) {
     return 'image/jpeg';
   }
+  if (normalizedFileName.endsWith('.dump')) {
+    return 'application/x-postgresql-dump';
+  }
 
   return getTextLikeMimeTypeFromFileName(normalizedFileName);
 }
@@ -681,9 +690,10 @@ export async function uploadAttachmentToServerApi(params: {
  * 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 type UserFacingUploadErrorCode = 'attachment_content_mismatch' | 'attachment_invalid';
 
 export const ATTACHMENT_CONTENT_MISMATCH_CODE: UserFacingUploadErrorCode = 'attachment_content_mismatch';
+export const ATTACHMENT_INVALID_CODE: UserFacingUploadErrorCode = 'attachment_invalid';
 
 export class AttachmentUploadApiError extends Error {
   readonly code: UserFacingUploadErrorCode;
@@ -710,12 +720,12 @@ function readStringProperty(value: object, key: string): string | undefined {
 }
 
 function isUserFacingUploadErrorCode(code: string): code is UserFacingUploadErrorCode {
-  return code === ATTACHMENT_CONTENT_MISMATCH_CODE;
+  return code === ATTACHMENT_CONTENT_MISMATCH_CODE || code === ATTACHMENT_INVALID_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},
+ * Returns undefined unless `code` is a recognized user-facing upload error,
  * 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.
  */