Part 6:  Ecosystems

5
import { lowerName, lowerNamespace } from '../strings.js'
6

7
interface PurlObject {
8
  name: string
9
  namespace?: string | undefined
10
  qualifiers?: Record<string, string> | undefined
11
  subpath?: string | undefined
12
  type?: string | undefined
13
  version?: string | undefined
14
}

21
export function normalize(purl: PurlObject): PurlObject {
22
  lowerNamespace(purl)
23
  lowerName(purl)
24
  return purl
25
}

5
import { lowerName, lowerNamespace } from '../strings.js'
6

7
interface PurlObject {
8
  name: string
9
  namespace?: string | undefined
10
  qualifiers?: Record<string, string> | undefined
11
  subpath?: string | undefined
12
  type?: string | undefined
13
  version?: string | undefined
14
}

21
export function normalize(purl: PurlObject): PurlObject {
22
  lowerNamespace(purl)
23
  lowerName(purl)
24
  return purl
25
}

8
import { PurlError } from '../error.js'
9
import { lowerName } from '../strings.js'
10
import { validateNoInjectionByType } from '../validate.js'
11

12
interface PurlObject {
13
  name: string
14
  namespace?: string | undefined
15
  qualifiers?: Record<string, string> | undefined
16
  subpath?: string | undefined
17
  type?: string | undefined
18
  version?: string | undefined
19
}

26
export function normalize(purl: PurlObject): PurlObject {
27
  lowerName(purl)
28
  return purl
29
}

36
export function validate(purl: PurlObject, throws: boolean): boolean {
37
  if (!purl.version || purl.version.length === 0) {
38
    if (throws) {
39
      throw new PurlError('bazel requires a "version" component')
40
    }
41
    return false
42
  }
43
  if (!validateNoInjectionByType('bazel', 'name', purl.name, throws)) {
44
    return false
45
  }
46
  return true
47
}

5
import { lowerName, lowerNamespace } from '../strings.js'
6
import { validateNoInjectionByType } from '../validate.js'
7

8
interface PurlObject {
9
  name: string
10
  namespace?: string | undefined
11
  qualifiers?: Record<string, string> | undefined
12
  subpath?: string | undefined
13
  type?: string | undefined
14
  version?: string | undefined
15
}

22
export function normalize(purl: PurlObject): PurlObject {
23
  lowerNamespace(purl)
24
  lowerName(purl)
25
  return purl
26
}

32
export function validate(purl: PurlObject, throws: boolean): boolean {
33
  if (
34
    !validateNoInjectionByType('bitbucket', 'namespace', purl.namespace, throws)
35
  ) {
36
    return false
37
  }
38
  if (!validateNoInjectionByType('bitbucket', 'name', purl.name, throws)) {
39
    return false
40
  }
41
  return true
42
}

5
import { lowerName } from '../strings.js'
6

7
interface PurlObject {
8
  name: string
9
  namespace?: string | undefined
10
  qualifiers?: Record<string, string> | undefined
11
  subpath?: string | undefined
12
  type?: string | undefined
13
  version?: string | undefined
14
}

21
export function normalize(purl: PurlObject): PurlObject {
22
  lowerName(purl)
23
  return purl
24
}

5
import { errorMessage } from '../error.js'
6
import { httpJson } from '@socketsecurity/lib/http-request'
7

8
import {
9
  ArrayPrototypeSome,
10
  StringPrototypeIncludes,
11
  encodeComponent,
12
} from '@socketsecurity/lib/primordials'
13
import { validateEmptyByType, validateNoInjectionByType } from '../validate.js'
14

15
import type { ExistsResult, ExistsOptions } from './npm.js'
16

17
interface PurlObject {
18
  name: string
19
  namespace?: string | undefined
20
  qualifiers?: Record<string, string> | undefined
21
  subpath?: string | undefined
22
  type?: string | undefined
23
  version?: string | undefined
24
}

64
export async function cargoExists(
65
  name: string,
66
  version?: string,
67
  options?: ExistsOptions,
68
): Promise<ExistsResult> {
69
  const cacheKey = version ? `cargo:${name}@${version}` : `cargo:${name}`
70

71
  // Try cache first if provided
72
  if (options?.cache) {
73
    const cached = await options.cache.get<ExistsResult>(cacheKey)
74
    if (cached !== undefined) {
75
      return cached
76
    }
77
  }
78

79
  const fetchResult = async (): Promise<ExistsResult> => {
80
    try {
81
      const url = `https://crates.io/api/v1/crates/${encodeComponent(name)}`
82

83
      const data = await httpJson<{
84
        crate?: { max_version?: string }
85
        versions?: Array<{ num?: string }>
86
      }>(url, {
87
        headers: {
88
          'User-Agent': '@socketregistry/packageurl-js',
89
        },
90
      })
91

92
      const latestVersion =
93
        data.crate?.['max_version'] || data.versions?.[0]?.['num']
94

95
      // If specific version requested, validate it exists
96
      if (version && data.versions) {
97
        const versionExists = ArrayPrototypeSome(
98
          data.versions,
99
          v => v.num === version,
100
        )
101
        if (!versionExists) {
102
          const result: ExistsResult = {
103
            exists: false,
104
            error: `Version ${version} not found`,
105
          }
106
          if (latestVersion !== undefined) {
107
            result.latestVersion = latestVersion
108
          }
109
          return result
110
        }
111
      }
112

113
      const result: ExistsResult = {
114
        exists: true,
115
      }
116
      if (latestVersion !== undefined) {
117
        result.latestVersion = latestVersion
118
      }
119
      return result
120
    } catch (e) {

122
      const error = errorMessage(e)

124
      return {
125
        exists: false,
126
        error: StringPrototypeIncludes(error, '404')
127
          ? 'Crate not found'
128
          : error,
129
      }
130
    }
131
  }
132

133
  const result = await fetchResult()
134

135
  // Only cache successful results to avoid negative cache poisoning
136
  // from transient failures (network errors, 5xx responses)
137
  if (options?.cache && result.exists) {
138
    await options.cache.set(cacheKey, Object.freeze(result))
139
  }
140

141
  return result
142
}

148
export function validate(purl: PurlObject, throws: boolean): boolean {
149
  if (
150
    !validateEmptyByType('cargo', 'namespace', purl.namespace, {
151
      throws,
152
    })
153
  ) {
154
    return false
155
  }
156
  if (!validateNoInjectionByType('cargo', 'name', purl.name, throws)) {
157
    return false
158
  }
159
  return true
160
}

5
import { httpJson } from '@socketsecurity/lib/http-request'
6

7
import { errorMessage, PurlError } from '../error.js'
8
import {
9
  ArrayPrototypeSome,
10
  StringPrototypeCharCodeAt,
11
  StringPrototypeIncludes,
12
  encodeComponent,
13
} from '@socketsecurity/lib/primordials'
14
import { validateNoInjectionByType } from '../validate.js'
15

16
import type { ExistsResult, ExistsOptions } from './npm.js'
17

18
interface PurlObject {
19
  name: string
20
  namespace?: string | undefined
21
  qualifiers?: Record<string, string> | undefined
22
  subpath?: string | undefined
23
  type?: string | undefined
24
  version?: string | undefined
25
}

54
export async function cocoapodsExists(
55
  name: string,
56
  version?: string,
57
  options?: ExistsOptions,
58
): Promise<ExistsResult> {
59
  const cacheKey = version
60
    ? `cocoapods:${name}@${version}`
61
    : `cocoapods:${name}`
62

63
  // Try cache first if provided
64
  if (options?.cache) {
65
    const cached = await options.cache.get<ExistsResult>(cacheKey)
66
    if (cached !== undefined) {
67
      return cached
68
    }
69
  }
70

71
  const fetchResult = async (): Promise<ExistsResult> => {
72
    try {
73
      const url = `https://trunk.cocoapods.org/api/v1/pods/${encodeComponent(name)}`
74

75
      const data = await httpJson<{
76
        versions?: Array<{ name?: string }>
77
      }>(url)
78

79
      const versions = data.versions
80
      if (!versions || versions.length === 0) {
81
        return { exists: false, error: 'No versions found' }
82
      }
83

84
      // Latest version is first in the array
85
      const latestVersion = versions[0]?.['name']
86

87
      if (version) {
88
        const versionExists = ArrayPrototypeSome(
89
          versions,
90
          v => v.name === version,
91
        )
92
        if (!versionExists) {
93
          const result: ExistsResult = {
94
            exists: false,
95
            error: `Version ${version} not found`,
96
          }
97
          if (latestVersion !== undefined) {
98
            result.latestVersion = latestVersion
99
          }
100
          return result
101
        }
102
      }
103

104
      const result: ExistsResult = { exists: true }
105
      if (latestVersion !== undefined) {
106
        result.latestVersion = latestVersion
107
      }
108
      return result
109
    } catch (e) {

111
      const error = errorMessage(e)
112
      return {
113
        exists: false,
114
        error: StringPrototypeIncludes(error, '404') ? 'Pod not found' : error,
115
      }

117
    }
118
  }
119

120
  const result = await fetchResult()
121

122
  // Only cache successful results to avoid negative cache poisoning
123
  // from transient failures (network errors, 5xx responses)
124
  if (options?.cache && result.exists) {
125
    await options.cache.set(cacheKey, Object.freeze(result))
126
  }
127

128
  return result
129
}

136
export function validate(purl: PurlObject, throws: boolean): boolean {
137
  const { name } = purl
138
  // `name` must not contain injection characters
139
  if (!validateNoInjectionByType('cocoapods', 'name', name, throws)) {
140
    return false
141
  }
142
  // `name` cannot contain a plus (`+`) character
143
  if (StringPrototypeIncludes(name, '+')) {
144
    if (throws) {
145
      throw new PurlError(
146
        'cocoapods "name" component cannot contain a plus (+) character',
147
      )
148
    }
149
    return false
150
  }
151
  // `name` cannot begin with a period (`.`)

153
    if (throws) {
154
      throw new PurlError(
155
        'cocoapods "name" component cannot begin with a period',
156
      )
157
    }
158
    return false
159
  }
160
  return true
161
}

5
import { errorMessage } from '../error.js'
6
import { httpJson } from '@socketsecurity/lib/http-request'
7

8
import {
9
  ArrayPrototypeSome,
10
  StringPrototypeIncludes,
11
  encodeComponent,
12
} from '@socketsecurity/lib/primordials'
13
import { lowerName, lowerNamespace } from '../strings.js'
14

15
import type { ExistsResult, ExistsOptions } from './npm.js'
16

17
interface PurlObject {
18
  name: string
19
  namespace?: string | undefined
20
  qualifiers?: Record<string, string> | undefined
21
  subpath?: string | undefined
22
  type?: string | undefined
23
  version?: string | undefined
24
}

31
export function normalize(purl: PurlObject): PurlObject {
32
  lowerNamespace(purl)
33
  lowerName(purl)
34
  return purl
35
}

64
export async function packagistExists(
65
  name: string,
66
  namespace?: string,
67
  version?: string,
68
  options?: ExistsOptions,
69
): Promise<ExistsResult> {
70
  if (!namespace) {
71
    return { exists: false, error: 'Composer requires namespace (vendor)' }
72
  }
73

74
  const packageName = `${namespace}/${name}`
75
  const cacheKey = version
76
    ? `composer:${packageName}@${version}`
77
    : `composer:${packageName}`
78

79
  if (options?.cache) {
80
    const cached = await options.cache.get<ExistsResult>(cacheKey)
81
    if (cached !== undefined) {
82
      return cached
83
    }
84
  }
85

86
  const fetchResult = async (): Promise<ExistsResult> => {
87
    try {
88
      const url = `https://repo.packagist.org/p2/${encodeComponent(packageName)}.json`
89

90
      const data = await httpJson<{
91
        packages?: {
92
          [key: string]: Array<{
93
            version?: string
94
            version_normalized?: string
95
          }>
96
        }
97
      }>(url)
98

99
      const packageVersions = data.packages?.[packageName]
100
      if (!packageVersions || packageVersions.length === 0) {
101
        return { exists: false, error: 'Package not found' }
102
      }
103

104
      // Find the latest stable version (highest `version_normalized` without `dev` suffix)
105
      let latestVersion: string | undefined
106
      for (const pkg of packageVersions) {
107
        const ver = pkg.version
108
        if (ver && !StringPrototypeIncludes(ver, 'dev-')) {
109
          latestVersion = ver
110
          break
111
        }
112
      }
113

114
      if (version) {
115
        const versionExists = ArrayPrototypeSome(
116
          packageVersions,
117
          pkg => pkg.version === version,
118
        )
119
        if (!versionExists) {
120
          const result: ExistsResult = {
121
            exists: false,
122
            error: `Version ${version} not found`,
123
          }
124
          if (latestVersion !== undefined) {
125
            result.latestVersion = latestVersion
126
          }
127
          return result
128
        }
129
      }
130

131
      const result: ExistsResult = { exists: true }
132
      if (latestVersion !== undefined) {
133
        result.latestVersion = latestVersion
134
      }
135
      return result
136
    } catch (e) {

138
      const error = errorMessage(e)
139
      return {
140
        exists: false,
141
        error: StringPrototypeIncludes(error, '404')
142
          ? 'Package not found'
143
          : error,
144
      }

146
    }
147
  }
148

149
  const result = await fetchResult()
150
  // Only cache successful results to avoid negative cache poisoning
151
  // from transient failures (network errors, 5xx responses)
152
  if (options?.cache && result.exists) {
153
    await options.cache.set(cacheKey, Object.freeze(result))
154
  }
155
  return result
156
}

5
import { PurlError } from '../error.js'
6
import { isNullishOrEmptyString } from '../lang.js'
7
import { validateNoInjectionByType } from '../validate.js'
8

9
interface PurlObject {
10
  name: string
11
  namespace?: string | undefined
12
  qualifiers?: Record<string, string> | undefined
13
  subpath?: string | undefined
14
  type?: string | undefined
15
  version?: string | undefined
16
}

24
export function validate(purl: PurlObject, throws: boolean): boolean {
25
  if (isNullishOrEmptyString(purl.namespace)) {
26
    if (purl.qualifiers?.['channel']) {
27
      if (throws) {
28
        throw new PurlError(
29
          'conan requires a "namespace" component when a "channel" qualifier is present',
30
        )
31
      }
32
      return false
33
    }
34
  } else if (isNullishOrEmptyString(purl.qualifiers)) {
35
    if (throws) {
36
      throw new PurlError(
37
        'conan requires a "qualifiers" component when a namespace is present',
38
      )
39
    }
40
    return false
41
  }
42
  if (
43
    !validateNoInjectionByType('conan', 'namespace', purl.namespace, throws)
44
  ) {
45
    return false
46
  }
47
  if (!validateNoInjectionByType('conan', 'name', purl.name, throws)) {
48
    return false
49
  }
50
  return true
51
}

5
import { errorMessage } from '../error.js'
6
import { httpJson } from '@socketsecurity/lib/http-request'
7

8
import {
9
  ArrayPrototypeIncludes,
10
  StringPrototypeIncludes,
11
  encodeComponent,
12
} from '@socketsecurity/lib/primordials'
13
import { lowerName } from '../strings.js'
14
import { validateEmptyByType, validateNoInjectionByType } from '../validate.js'
15

16
import type { ExistsOptions, ExistsResult } from './npm.js'
17

18
interface PurlObject {
19
  name: string
20
  namespace?: string | undefined
21
  qualifiers?: Record<string, string> | undefined
22
  subpath?: string | undefined
23
  type?: string | undefined
24
  version?: string | undefined
25
}

32
export function normalize(purl: PurlObject): PurlObject {
33
  lowerName(purl)
34
  return purl
35
}

41
export function validate(purl: PurlObject, throws: boolean): boolean {
42
  if (
43
    !validateEmptyByType('conda', 'namespace', purl.namespace, {
44
      throws,
45
    })
46
  ) {
47
    return false
48
  }
49
  if (!validateNoInjectionByType('conda', 'name', purl.name, throws)) {
50
    return false
51
  }
52
  return true
53
}

98
export async function condaExists(
99
  name: string,
100
  version?: string,
101
  channel?: string,
102
  options?: ExistsOptions,
103
): Promise<ExistsResult> {
104
  // Use provided channel or default to `conda-forge` (most popular community channel)
105
  const channelName = channel || 'conda-forge'
106
  const cacheKey = version
107
    ? `conda:${channelName}/${name}@${version}`
108
    : `conda:${channelName}/${name}`
109

110
  // Try cache first if provided
111
  if (options?.cache) {
112
    const cached = await options.cache.get<ExistsResult>(cacheKey)
113
    if (cached !== undefined) {
114
      return cached
115
    }
116
  }
117

118
  const fetchResult = async (): Promise<ExistsResult> => {
119
    try {
120
      const encodedChannel = encodeComponent(channelName)
121
      const encodedName = encodeComponent(name)
122
      const url = `https://api.anaconda.org/package/${encodedChannel}/${encodedName}`
123

124
      const data = await httpJson<{
125
        latest_version?: string
126
        versions?: string[]
127
      }>(url)
128

129
      const latestVersion = data.latest_version
130

131
      // If specific version requested, validate it exists
132
      if (version) {
133
        if (!data.versions || !ArrayPrototypeIncludes(data.versions, version)) {
134
          const result: ExistsResult = {
135
            exists: false,
136
            error: `Version ${version} not found`,
137
          }
138
          if (latestVersion !== undefined) {
139
            result.latestVersion = latestVersion
140
          }
141
          return result
142
        }
143
      }
144

145
      const result: ExistsResult = {
146
        exists: true,
147
      }
148
      if (latestVersion !== undefined) {
149
        result.latestVersion = latestVersion
150
      }
151
      return result
152
    } catch (e) {

154
      const error = errorMessage(e)

156
      return {
157
        exists: false,
158
        error: StringPrototypeIncludes(error, '404')
159
          ? 'Package not found'
160
          : error,
161
      }
162
    }
163
  }
164

165
  const result = await fetchResult()
166

167
  // Only cache successful results to avoid negative cache poisoning
168
  // from transient failures (network errors, 5xx responses)
169
  if (options?.cache && result.exists) {
170
    await options.cache.set(cacheKey, Object.freeze(result))
171
  }
172

173
  return result
174
}

5
import { httpJson } from '@socketsecurity/lib/http-request'
6

7
import { errorMessage, PurlError } from '../error.js'
8
import {
9
  StringPrototypeIncludes,
10
  StringPrototypeToUpperCase,
11
  encodeComponent,
12
} from '@socketsecurity/lib/primordials'
13
import { validateNoInjectionByType } from '../validate.js'
14

15
import type { ExistsResult, ExistsOptions } from './npm.js'
16

17
interface PurlObject {
18
  name: string
19
  namespace?: string | undefined
20
  qualifiers?: Record<string, string> | undefined
21
  subpath?: string | undefined
22
  type?: string | undefined
23
  version?: string | undefined
24
}

53
export async function cpanExists(
54
  name: string,
55
  version?: string,
56
  options?: ExistsOptions,
57
): Promise<ExistsResult> {
58
  const cacheKey = version ? `cpan:${name}@${version}` : `cpan:${name}`
59

60
  // Try cache first if provided
61
  if (options?.cache) {
62
    const cached = await options.cache.get<ExistsResult>(cacheKey)
63
    if (cached !== undefined) {
64
      return cached
65
    }
66
  }
67

68
  const fetchResult = async (): Promise<ExistsResult> => {
69
    try {
70
      const url = `https://fastapi.metacpan.org/v1/module/${encodeComponent(name)}`
71

72
      const data = await httpJson<{
73
        version?: string
74
      }>(url)
75

76
      const latestVersion = data.version
77

78
      if (version) {
79
        // Check specific version
80
        const versionUrl = `https://fastapi.metacpan.org/v1/module/${encodeComponent(name)}/${encodeComponent(version)}`
81
        try {
82
          await httpJson(versionUrl)
83
        } catch {
84
          const result: ExistsResult = {
85
            exists: false,
86
            error: `Version ${version} not found`,
87
          }
88
          if (latestVersion !== undefined) {
89
            result.latestVersion = latestVersion
90
          }
91
          return result
92
        }
93
      }
94

95
      const result: ExistsResult = { exists: true }
96
      if (latestVersion !== undefined) {
97
        result.latestVersion = latestVersion
98
      }
99
      return result
100
    } catch (e) {

102
      const error = errorMessage(e)
103
      return {
104
        exists: false,
105
        error: StringPrototypeIncludes(error, '404')
106
          ? 'Module not found'
107
          : error,
108
      }

110
    }
111
  }
112

113
  const result = await fetchResult()
114

115
  // Only cache successful results to avoid negative cache poisoning
116
  // from transient failures (network errors, 5xx responses)
117
  if (options?.cache && result.exists) {
118
    await options.cache.set(cacheKey, Object.freeze(result))
119
  }
120

121
  return result
122
}

128
export function validate(purl: PurlObject, throws: boolean): boolean {
129
  const { namespace } = purl
130
  if (namespace && namespace !== StringPrototypeToUpperCase(namespace)) {
131
    if (throws) {
132
      throw new PurlError('cpan "namespace" component must be UPPERCASE')
133
    }
134
    return false
135
  }
136
  if (!validateNoInjectionByType('cpan', 'namespace', namespace, throws)) {
137
    return false
138
  }
139
  if (!validateNoInjectionByType('cpan', 'name', purl.name, throws)) {
140
    return false
141
  }
142
  return true
143
}

5
import { errorMessage } from '../error.js'
6
import { httpJson } from '@socketsecurity/lib/http-request'
7

8
import {
9
  ArrayPrototypeIncludes,
10
  StringPrototypeIncludes,
11
  encodeComponent,
12
} from '@socketsecurity/lib/primordials'
13
import {
14
  validateNoInjectionByType,
15
  validateRequiredByType,
16
} from '../validate.js'
17

18
import type { ExistsResult, ExistsOptions } from './npm.js'
19

20
interface PurlObject {
21
  name: string
22
  namespace?: string | undefined
23
  qualifiers?: Record<string, string> | undefined
24
  subpath?: string | undefined
25
  type?: string | undefined
26
  version?: string | undefined
27
}

57
export async function cranExists(
58
  name: string,
59
  version?: string,
60
  options?: ExistsOptions,
61
): Promise<ExistsResult> {
62
  const cacheKey = version ? `cran:${name}@${version}` : `cran:${name}`
63

64
  // Try cache first if provided
65
  if (options?.cache) {
66
    const cached = await options.cache.get<ExistsResult>(cacheKey)
67
    if (cached !== undefined) {
68
      return cached
69
    }
70
  }
71

72
  const fetchResult = async (): Promise<ExistsResult> => {
73
    try {
74
      // CRAN provides a JSON API via r-universe
75
      const url = `https://cran.r-universe.dev/api/packages/${encodeComponent(name)}`
76

77
      const data = await httpJson<{
78
        Version?: string
79
        versions?: string[]
80
      }>(url)
81

82
      const latestVersion = data.Version
83

84
      if (version) {
85
        const versions = data.versions || []
86
        if (!ArrayPrototypeIncludes(versions, version)) {
87
          const result: ExistsResult = {
88
            exists: false,
89
            error: `Version ${version} not found`,
90
          }
91
          if (latestVersion !== undefined) {
92
            result.latestVersion = latestVersion
93
          }
94
          return result
95
        }
96
      }
97

98
      const result: ExistsResult = { exists: true }
99
      if (latestVersion !== undefined) {
100
        result.latestVersion = latestVersion
101
      }
102
      return result
103
    } catch (e) {

105
      const error = errorMessage(e)
106
      return {
107
        exists: false,
108
        error: StringPrototypeIncludes(error, '404')
109
          ? 'Package not found'
110
          : error,
111
      }

113
    }
114
  }
115

116
  const result = await fetchResult()
117

118
  // Only cache successful results to avoid negative cache poisoning
119
  // from transient failures (network errors, 5xx responses)
120
  if (options?.cache && result.exists) {
121
    await options.cache.set(cacheKey, Object.freeze(result))
122
  }
123

124
  return result
125
}

131
export function validate(purl: PurlObject, throws: boolean): boolean {
132
  if (
133
    !validateRequiredByType('cran', 'version', purl.version, {
134
      throws,
135
    })
136
  ) {
137
    return false
138
  }
139
  if (!validateNoInjectionByType('cran', 'name', purl.name, throws)) {
140
    return false
141
  }
142
  return true
143
}

5
import { lowerName, lowerNamespace } from '../strings.js'
6

7
interface PurlObject {
8
  name: string
9
  namespace?: string | undefined
10
  qualifiers?: Record<string, string> | undefined
11
  subpath?: string | undefined
12
  type?: string | undefined
13
  version?: string | undefined
14
}

21
export function normalize(purl: PurlObject): PurlObject {
22
  lowerNamespace(purl)
23
  lowerName(purl)
24
  return purl
25
}

5
import { errorMessage } from '../error.js'
6
import { httpJson } from '@socketsecurity/lib/http-request'
7

8
import {
9
  StringPrototypeIncludes,
10
  encodeComponent,
11
} from '@socketsecurity/lib/primordials'
12
import { lowerName } from '../strings.js'
13
import { validateNoInjectionByType } from '../validate.js'
14

15
import type { ExistsOptions, ExistsResult } from './npm.js'
16

17
interface PurlObject {
18
  name: string
19
  namespace?: string | undefined
20
  qualifiers?: Record<string, string> | undefined
21
  subpath?: string | undefined
22
  type?: string | undefined
23
  version?: string | undefined
24
}

31
export function normalize(purl: PurlObject): PurlObject {
32
  lowerName(purl)
33
  return purl
34
}

40
export function validate(purl: PurlObject, throws: boolean): boolean {
41
  if (
42
    !validateNoInjectionByType('docker', 'namespace', purl.namespace, throws)
43
  ) {
44
    return false
45
  }
46
  if (!validateNoInjectionByType('docker', 'name', purl.name, throws)) {
47
    return false
48
  }
49
  return true
50
}

94
export async function dockerExists(
95
  name: string,
96
  namespace?: string,
97
  version?: string,
98
  options?: ExistsOptions,
99
): Promise<ExistsResult> {
100
  // Default namespace to `'library'` for official images if not specified
101
  const repo = namespace ? `${namespace}/${name}` : name
102
  const cacheKey = version ? `docker:${repo}:${version}` : `docker:${repo}`
103

104
  // Try cache first if provided
105
  if (options?.cache) {
106
    const cached = await options.cache.get<ExistsResult>(cacheKey)
107
    if (cached !== undefined) {
108
      return cached
109
    }
110
  }
111

112
  const fetchResult = async (): Promise<ExistsResult> => {
113
    try {
114
      // Encode each path segment separately to preserve the `/` delimiter
115
      const encodedRepo = namespace
116
        ? `${encodeComponent(namespace)}/${encodeComponent(name)}`
117
        : encodeComponent(name)
118
      const url = `https://hub.docker.com/v2/repositories/${encodedRepo}`
119

120
      const data = await httpJson<{
121
        name?: string
122
      }>(url)
123

124
      // Docker Hub doesn't provide a simple `"latest version"` - tags need separate API call
125
      // For now, we just verify the repository exists
126
      if (!data.name) {
127
        return {
128
          exists: false,
129
          error: 'Image not found',
130
        }
131
      }
132

133
      // If specific tag requested, verify it exists
134
      if (version) {
135
        try {
136
          const tagUrl = `https://hub.docker.com/v2/repositories/${encodedRepo}/tags/${encodeComponent(version)}`
137
          await httpJson(tagUrl)
138
        } catch (e) {

140
          const error = errorMessage(e)

142
          return {
143
            exists: false,
144
            error: StringPrototypeIncludes(error, '404')
145
              ? `Tag ${version} not found`
146
              : error,
147
          }
148
        }
149
      }
150

151
      return {
152
        exists: true,
153
        latestVersion: version || 'latest',
154
      }
155
    } catch (e) {

157
      const error = errorMessage(e)

159
      return {
160
        exists: false,
161
        error: StringPrototypeIncludes(error, '404')
162
          ? 'Image not found'
163
          : error,
164
      }
165
    }
166
  }
167

168
  const result = await fetchResult()
169

170
  // Only cache successful results to avoid negative cache poisoning
171
  // from transient failures (network errors, 5xx responses)
172
  if (options?.cache && result.exists) {
173
    await options.cache.set(cacheKey, Object.freeze(result))
174
  }
175

176
  return result
177
}

5
import { httpJson } from '@socketsecurity/lib/http-request'
6

7
import { errorMessage } from '../error.js'
8
import {
9
  ArrayIsArray,
10
  ArrayPrototypeSome,
11
  StringPrototypeIncludes,
12
  encodeComponent,
13
} from '@socketsecurity/lib/primordials'
14
import { validateEmptyByType, validateNoInjectionByType } from '../validate.js'
15

16
import type { ExistsResult, ExistsOptions } from './npm.js'
17

18
interface PurlObject {
19
  name: string
20
  namespace?: string | undefined
21
  qualifiers?: Record<string, string> | undefined
22
  subpath?: string | undefined
23
  type?: string | undefined
24
  version?: string | undefined
25
}

63
export async function gemExists(
64
  name: string,
65
  version?: string,
66
  options?: ExistsOptions,
67
): Promise<ExistsResult> {
68
  const cacheKey = version ? `gem:${name}@${version}` : `gem:${name}`
69

70
  // Try cache first if provided
71
  if (options?.cache) {
72
    const cached = await options.cache.get<ExistsResult>(cacheKey)
73
    if (cached !== undefined) {
74
      return cached
75
    }
76
  }
77

78
  const fetchResult = async (): Promise<ExistsResult> => {
79
    try {
80
      const url = `https://rubygems.org/api/v1/versions/${encodeComponent(name)}.json`
81

82
      const data = await httpJson<Array<{ number?: string }>>(url)
83

84
      if (!ArrayIsArray(data) || data.length === 0) {
85
        return {
86
          exists: false,
87
          error: 'No versions found',
88
        }
89
      }
90

91
      const latestVersion = data[0]?.['number']
92

93
      // If specific version requested, validate it exists
94
      if (version) {
95
        const versionExists = ArrayPrototypeSome(
96
          data,
97
          v => v.number === version,
98
        )
99
        if (!versionExists) {
100
          const result: ExistsResult = {
101
            exists: false,
102
            error: `Version ${version} not found`,
103
          }
104
          if (latestVersion !== undefined) {
105
            result.latestVersion = latestVersion
106
          }
107
          return result
108
        }
109
      }
110

111
      const result: ExistsResult = {
112
        exists: true,
113
      }
114
      if (latestVersion !== undefined) {
115
        result.latestVersion = latestVersion
116
      }
117
      return result
118
    } catch (e) {

120
      const error = errorMessage(e)
121
      return {
122
        exists: false,
123
        error: StringPrototypeIncludes(error, '404') ? 'Gem not found' : error,
124
      }

126
    }
127
  }
128

129
  const result = await fetchResult()
130

131
  // Only cache successful results to avoid negative cache poisoning
132
  // from transient failures (network errors, 5xx responses)
133
  if (options?.cache && result.exists) {
134
    await options.cache.set(cacheKey, Object.freeze(result))
135
  }
136

137
  return result
138
}

144
export function validate(purl: PurlObject, throws: boolean): boolean {
145
  if (
146
    !validateEmptyByType('gem', 'namespace', purl.namespace, {
147
      throws,
148
    })
149
  ) {
150
    return false
151
  }
152
  if (!validateNoInjectionByType('gem', 'name', purl.name, throws)) {
153
    return false
154
  }
155
  return true
156
}

8
interface PurlObject {
9
  name: string
10
  namespace?: string | undefined
11
  qualifiers?: Record<string, string> | undefined
12
  subpath?: string | undefined
13
  type?: string | undefined
14
  version?: string | undefined
15
}

22
export function normalize(purl: PurlObject): PurlObject {
23
  return purl
24
}

5
import { lowerName, lowerNamespace } from '../strings.js'
6
import { validateNoInjectionByType } from '../validate.js'
7

8
interface PurlObject {
9
  name: string
10
  namespace?: string | undefined
11
  qualifiers?: Record<string, string> | undefined
12
  subpath?: string | undefined
13
  type?: string | undefined
14
  version?: string | undefined
15
}

22
export function normalize(purl: PurlObject): PurlObject {
23
  lowerNamespace(purl)
24
  lowerName(purl)
25
  return purl
26
}

32
export function validate(purl: PurlObject, throws: boolean): boolean {
33
  if (
34
    !validateNoInjectionByType('github', 'namespace', purl.namespace, throws)
35
  ) {
36
    return false
37
  }
38
  if (!validateNoInjectionByType('github', 'name', purl.name, throws)) {
39
    return false
40
  }
41
  return true
42
}

5
import { lowerName, lowerNamespace } from '../strings.js'
6
import { validateNoInjectionByType } from '../validate.js'
7

8
interface PurlObject {
9
  name: string
10
  namespace?: string | undefined
11
  qualifiers?: Record<string, string> | undefined
12
  subpath?: string | undefined
13
  type?: string | undefined
14
  version?: string | undefined
15
}

22
export function normalize(purl: PurlObject): PurlObject {
23
  lowerNamespace(purl)
24
  lowerName(purl)
25
  return purl
26
}

32
export function validate(purl: PurlObject, throws: boolean): boolean {
33
  if (
34
    !validateNoInjectionByType('gitlab', 'namespace', purl.namespace, throws)
35
  ) {
36
    return false
37
  }
38
  if (!validateNoInjectionByType('gitlab', 'name', purl.name, throws)) {
39
    return false
40
  }
41
  return true
42
}

30
import { httpJson } from '@socketsecurity/lib/http-request'
31

32
import { errorMessage, PurlError } from '../error.js'
33
import {
34
  ArrayPrototypeJoin,
35
  encodeComponent,
36
  StringPrototypeCharCodeAt,
37
  StringPrototypeIncludes,
38
  StringPrototypeReplace,
39
  StringPrototypeSlice,
40
  StringPrototypeSplit,
41
  StringPrototypeToLowerCase,
42
} from '@socketsecurity/lib/primordials'
43
import { isSemverString } from '../strings.js'
44
import { validateNoInjectionByType } from '../validate.js'
45

46
import type { ExistsResult, ExistsOptions } from './npm.js'
47

48
interface PurlObject {
49
  name: string
50
  namespace?: string | undefined
51
  qualifiers?: Record<string, string> | undefined
52
  subpath?: string | undefined
53
  type?: string | undefined
54
  version?: string | undefined
55
}

90
export async function golangExists(
91
  name: string,
92
  namespace?: string,
93
  version?: string,
94
  options?: ExistsOptions,
95
): Promise<ExistsResult> {
96
  const modulePath = namespace ? `${namespace}/${name}` : name
97
  const cacheKey = version
98
    ? `golang:${modulePath}@${version}`
99
    : `golang:${modulePath}`
100

101
  if (options?.cache) {
102
    const cached = await options.cache.get<ExistsResult>(cacheKey)
103
    if (cached !== undefined) {
104
      return cached
105
    }
106
  }
107

108
  const fetchResult = async (): Promise<ExistsResult> => {
109
    try {
110
      // Encode the module path for the URL
111
      // Go proxy uses case-encoded paths where uppercase letters are `!lowercase`
112
      const parts = StringPrototypeSplit(modulePath, '/' as any)
113
      for (let i = 0; i < parts.length; i++) {
114
        parts[i] = encodeComponent(
115
          StringPrototypeReplace(
116
            parts[i]!,
117
            /[A-Z]/g,
118
            letter => `!${StringPrototypeToLowerCase(letter)}`,
119
          ),
120
        )
121
      }
122
      const encodedPath = ArrayPrototypeJoin(parts, '/')
123

124
      const url = `https://proxy.golang.org/${encodedPath}/@latest`
125

126
      const data = await httpJson<{
127
        Version?: string
128
        Time?: string
129
      }>(url)
130

131
      const latestVersion = data.Version
132

133
      if (version) {
134
        const versionUrl = `https://proxy.golang.org/${encodedPath}/@v/${encodeComponent(version)}.info`
135
        try {
136
          await httpJson(versionUrl)
137
        } catch {
138
          const result: ExistsResult = {
139
            exists: false,
140
            error: `Version ${version} not found`,
141
          }
142
          if (latestVersion !== undefined) {
143
            result.latestVersion = latestVersion
144
          }
145
          return result
146
        }
147
      }
148

149
      const result: ExistsResult = { exists: true }
150
      if (latestVersion !== undefined) {
151
        result.latestVersion = latestVersion
152
      }
153
      return result
154
    } catch (e) {

156
      const error = errorMessage(e)
157
      return {
158
        exists: false,
159
        error:
160
          StringPrototypeIncludes(error, '404') ||
161
          StringPrototypeIncludes(error, '410')
162
            ? 'Module not found'
163
            : error,
164
      }

166
    }
167
  }
168

169
  const result = await fetchResult()
170
  // Only cache successful results to avoid negative cache poisoning
171
  // from transient failures (network errors, 5xx responses)
172
  if (options?.cache && result.exists) {
173
    await options.cache.set(cacheKey, Object.freeze(result))
174
  }
175
  return result
176
}

183
export function validate(purl: PurlObject, throws: boolean): boolean {
184
  if (
185
    !validateNoInjectionByType('golang', 'namespace', purl.namespace, throws)
186
  ) {
187
    return false
188
  }
189
  if (!validateNoInjectionByType('golang', 'name', purl.name, throws)) {
190
    return false
191
  }
192
  // Still being lenient here since the standard changes aren't official
193
  // Pending spec change: https://github.com/package-url/purl-spec/pull/196
194
  const { version } = purl
195
  const length = typeof version === 'string' ? version.length : 0
196
  // If the version starts with a `"v"` then ensure its a valid semver version
197
  // This, by semver semantics, also supports pseudo-version number
198
  // https://go.dev/doc/modules/version-numbers#pseudo-version-number
199
  if (
200
    length &&

202
    !isSemverString(StringPrototypeSlice(version!, 1))
203
  ) {
204
    if (throws) {
205
      throw new PurlError(
206
        'golang "version" component starting with a "v" must be followed by a valid semver version',
207
      )
208
    }
209
    return false
210
  }
211
  return true
212
}

5
import { errorMessage } from '../error.js'
6
import { httpJson } from '@socketsecurity/lib/http-request'
7

8
import {
9
  ArrayPrototypeIncludes,
10
  StringPrototypeIncludes,
11
  encodeComponent,
12
} from '@socketsecurity/lib/primordials'
13

14
import type { ExistsResult, ExistsOptions } from './npm.js'

43
export async function hackageExists(
44
  name: string,
45
  version?: string,
46
  options?: ExistsOptions,
47
): Promise<ExistsResult> {
48
  const cacheKey = version ? `hackage:${name}@${version}` : `hackage:${name}`
49

50
  // Try cache first if provided
51
  if (options?.cache) {
52
    const cached = await options.cache.get<ExistsResult>(cacheKey)
53
    if (cached !== undefined) {
54
      return cached
55
    }
56
  }
57

58
  const fetchResult = async (): Promise<ExistsResult> => {
59
    try {
60
      const url = `https://hackage.haskell.org/package/${encodeComponent(name)}/preferred`
61

62
      const data = await httpJson<{
63
        'normal-version'?: string[]
64
      }>(url)
65

66
      const versions = data['normal-version'] || []
67
      if (versions.length === 0) {
68
        return { exists: false, error: 'No versions found' }
69
      }
70

71
      // Latest version is typically the last in the array
72
      const latestVersion = versions[versions.length - 1]
73

74
      if (version) {
75
        if (!ArrayPrototypeIncludes(versions, version)) {
76
          const result: ExistsResult = {
77
            exists: false,
78
            error: `Version ${version} not found`,
79
          }
80
          if (latestVersion !== undefined) {
81
            result.latestVersion = latestVersion
82
          }
83
          return result
84
        }
85
      }
86

87
      const result: ExistsResult = { exists: true }
88
      if (latestVersion !== undefined) {
89
        result.latestVersion = latestVersion
90
      }
91
      return result
92
    } catch (e) {

94
      const error = errorMessage(e)
95
      return {
96
        exists: false,
97
        error: StringPrototypeIncludes(error, '404')
98
          ? 'Package not found'
99
          : error,
100
      }

102
    }
103
  }
104

105
  const result = await fetchResult()
106

107
  // Only cache successful results to avoid negative cache poisoning
108
  // from transient failures (network errors, 5xx responses)
109
  if (options?.cache && result.exists) {
110
    await options.cache.set(cacheKey, Object.freeze(result))
111
  }
112

113
  return result
114
}

5
import { errorMessage } from '../error.js'
6
import { httpJson } from '@socketsecurity/lib/http-request'
7

8
import {
9
  ArrayPrototypeSome,
10
  StringPrototypeIncludes,
11
  encodeComponent,
12
} from '@socketsecurity/lib/primordials'
13
import { lowerName, lowerNamespace } from '../strings.js'
14
import { validateNoInjectionByType } from '../validate.js'
15

16
import type { ExistsResult, ExistsOptions } from './npm.js'
17

18
interface PurlObject {
19
  name: string
20
  namespace?: string | undefined
21
  qualifiers?: Record<string, string> | undefined
22
  subpath?: string | undefined
23
  type?: string | undefined
24
  version?: string | undefined
25
}

54
export async function hexExists(
55
  name: string,
56
  version?: string,
57
  options?: ExistsOptions,
58
): Promise<ExistsResult> {
59
  const cacheKey = version ? `hex:${name}@${version}` : `hex:${name}`
60

61
  if (options?.cache) {
62
    const cached = await options.cache.get<ExistsResult>(cacheKey)
63
    if (cached !== undefined) {
64
      return cached
65
    }
66
  }
67

68
  const fetchResult = async (): Promise<ExistsResult> => {
69
    try {
70
      const url = `https://hex.pm/api/packages/${encodeComponent(name)}`
71

72
      const data = await httpJson<{
73
        latest_version?: string
74
        releases?: Array<{
75
          version?: string
76
        }>
77
      }>(url)
78

79
      const latestVersion = data.latest_version
80

81
      if (version) {
82
        const releases = data.releases || []
83
        const versionExists = ArrayPrototypeSome(
84
          releases,
85
          r => r.version === version,
86
        )
87
        if (!versionExists) {
88
          const result: ExistsResult = {
89
            exists: false,
90
            error: `Version ${version} not found`,
91
          }
92
          if (latestVersion !== undefined) {
93
            result.latestVersion = latestVersion
94
          }
95
          return result
96
        }
97
      }
98

99
      const result: ExistsResult = { exists: true }
100
      if (latestVersion !== undefined) {
101
        result.latestVersion = latestVersion
102
      }
103
      return result
104
    } catch (e) {

106
      const error = errorMessage(e)
107
      return {
108
        exists: false,
109
        error: StringPrototypeIncludes(error, '404')
110
          ? 'Package not found'
111
          : error,
112
      }

114
    }
115
  }
116

117
  const result = await fetchResult()
118
  // Only cache successful results to avoid negative cache poisoning
119
  // from transient failures (network errors, 5xx responses)
120
  if (options?.cache && result.exists) {
121
    await options.cache.set(cacheKey, Object.freeze(result))
122
  }
123
  return result
124
}

130
export function normalize(purl: PurlObject): PurlObject {
131
  lowerNamespace(purl)
132
  lowerName(purl)
133
  return purl
134
}

140
export function validate(purl: PurlObject, throws: boolean): boolean {
141
  if (!validateNoInjectionByType('hex', 'namespace', purl.namespace, throws)) {
142
    return false
143
  }
144
  if (!validateNoInjectionByType('hex', 'name', purl.name, throws)) {
145
    return false
146
  }
147
  return true
148
}

5
import { lowerVersion } from '../strings.js'
6

7
interface PurlObject {
8
  name: string
9
  namespace?: string | undefined
10
  qualifiers?: Record<string, string> | undefined
11
  subpath?: string | undefined
12
  type?: string | undefined
13
  version?: string | undefined
14
}

21
export function normalize(purl: PurlObject): PurlObject {
22
  lowerVersion(purl)
23
  return purl
24
}

8
import { validateEmptyByType, validateNoInjectionByType } from '../validate.js'
9

10
interface PurlObject {
11
  name: string
12
  namespace?: string | undefined
13
  qualifiers?: Record<string, string> | undefined
14
  subpath?: string | undefined
15
  type?: string | undefined
16
  version?: string | undefined
17
}

24
export function normalize(purl: PurlObject): PurlObject {
25
  return purl
26
}

32
export function validate(purl: PurlObject, throws: boolean): boolean {
33
  if (
34
    !validateEmptyByType('julia', 'namespace', purl.namespace, {
35
      throws,
36
    })
37
  ) {
38
    return false
39
  }
40
  if (!validateNoInjectionByType('julia', 'name', purl.name, throws)) {
41
    return false
42
  }
43
  return true
44
}