0
# Package Publishing
1

2
Core functionality for publishing npm packages to registries with support for provenance attestation, custom tags, and access control.
3

4
## Capabilities
5

6
### Publish Function
7

8
Publishes a package to the npm registry with comprehensive options for access control, provenance, and integrity verification.
9

10
```javascript { .api }
11
/**
12
 * Publishes a package to the npm registry
13
 * @param manifest - Parsed package.json manifest for the package being published
14
 * @param tarballData - Buffer containing the tarball data for the package
15
 * @param opts - Configuration options extending npm-registry-fetch options
16
 * @returns Promise resolving to response object with optional transparencyLogUrl
17
 */
18
function publish(manifest: Object, tarballData: Buffer, opts?: PublishOptions): Promise<PublishResult>;
19

20
interface PublishOptions {
21
  /** Access level for scoped packages: "public" or "restricted" (default: "public") */
22
  access?: 'public' | 'restricted';
23
  /** Tag to register the package with (default: "latest") */
24
  defaultTag?: string;
25
  /** Hashing algorithms for integrity generation (default: ["sha512"], always includes "sha1") */
26
  algorithms?: string[];
27
  /** Custom npm version string for _npmVersion field (identifies the publishing client) */
28
  npmVersion?: string;
29
  /** Enable automatic provenance generation in CI environments */
30
  provenance?: boolean;
31
  /** Path to external provenance statement file */
32
  provenanceFile?: string;
33
  /** Authentication token for registry */
34
  token?: string;
35
  /** Registry URL */
36
  registry?: string;
37
  /** Force publish even with validation warnings */
38
  force?: boolean;
39
}
40

41
interface PublishResult {
42
  /** Optional transparency log URL for provenance */
43
  transparencyLogUrl?: string;
44
}
45
```
46

47
**Usage Examples:**
48

49
```javascript
50
const { publish } = require('libnpmpublish');
51
const fs = require('fs');
52

53
// Basic publishing
54
const manifest = {
55
  name: 'my-package',
56
  version: '1.0.0',
57
  description: 'My package description'
58
};
59

60
const tarballData = fs.readFileSync('my-package-1.0.0.tgz');
61

62
await publish(manifest, tarballData, {
63
  token: 'npm_1234567890abcdef',
64
  registry: 'https://registry.npmjs.org/'
65
});
66

67
// Publishing with provenance in CI
68
await publish(manifest, tarballData, {
69
  token: 'npm_1234567890abcdef',
70
  provenance: true,
71
  access: 'public'
72
});
73

74
// Publishing scoped package with restricted access
75
const scopedManifest = {
76
  name: '@myorg/private-package',
77
  version: '1.0.0',
78
  description: 'Private organizational package'
79
};
80

81
await publish(scopedManifest, tarballData, {
82
  token: 'npm_1234567890abcdef',
83
  access: 'restricted'
84
});
85

86
// Publishing with custom tag and algorithms
87
await publish(manifest, tarballData, {
88
  token: 'npm_1234567890abcdef',
89
  defaultTag: 'beta',
90
  algorithms: ['sha512', 'sha256'],
91
  npmVersion: 'my-publish-tool@2.0.0'
92
});
93
```
94

95
### Access Control
96

97
Controls whether packages are published as public or restricted (scoped packages only).
98

99
- **Public**: Package is publicly accessible to all users
100
- **Restricted**: Package access is limited to organization members (scoped packages only)
101
- **Unscoped packages**: Always public, cannot be restricted
102

103
```javascript
104
// Public scoped package
105
await publish(manifest, tarballData, {
106
  access: 'public',  // default
107
  token: 'npm_token'
108
});
109

110
// Restricted scoped package
111
await publish(manifest, tarballData, {
112
  access: 'restricted',
113
  token: 'npm_token'
114
});
115
```
116

117
### Provenance Support
118

119
Automatic generation of signed provenance statements for supply chain security in supported CI environments.
120

121
```javascript { .api }
122
interface ProvenanceOptions {
123
  /** Enable automatic provenance generation (requires CI environment) */
124
  provenance?: boolean;
125
  /** Path to externally-generated provenance file */
126
  provenanceFile?: string;
127
}
128
```
129

130
**Supported CI Environments:**
131
- **GitHub Actions**: Requires "write" access to "id-token" permission
132
- **GitLab CI**: Requires SIGSTORE_ID_TOKEN with "sigstore" audience
133

134
**Usage Examples:**
135

136
```javascript
137
// Automatic provenance in GitHub Actions
138
await publish(manifest, tarballData, {
139
  token: 'npm_token',
140
  provenance: true,
141
  access: 'public'  // Required for provenance
142
});
143

144
// External provenance file
145
await publish(manifest, tarballData, {
146
  token: 'npm_token',
147
  provenanceFile: './provenance.sigstore'
148
});
149
```
150

151
### Integrity Generation
152

153
Generates cryptographic hashes for package verification using configurable algorithms.
154

155
```javascript { .api }
156
interface IntegrityOptions {
157
  /** Hashing algorithms for integrity generation (default: ["sha512"]) */
158
  algorithms?: string[];
159
}
160
```
161

162
**Supported Algorithms:**
163
- **sha512** (default): Primary integrity hash
164
- **sha256**: Additional integrity hash
165
- **sha1**: Legacy shasum for compatibility
166

167
**Usage Example:**
168

169
```javascript
170
await publish(manifest, tarballData, {
171
  token: 'npm_token',
172
  algorithms: ['sha512', 'sha256', 'sha1']
173
});
174
```
175

176
### Tag Management
177

178
Controls which dist-tag the package version is published under.
179

180
```javascript
181
// Publish to latest tag (default)
182
await publish(manifest, tarballData, {
183
  token: 'npm_token'
184
  // defaultTag: 'latest' is implicit
185
});
186

187
// Publish to beta tag
188
await publish(manifest, tarballData, {
189
  token: 'npm_token',
190
  defaultTag: 'beta'
191
});
192

193
// Use manifest tag if specified
194
const manifestWithTag = {
195
  ...manifest,
196
  tag: 'alpha'
197
};
198
await publish(manifestWithTag, tarballData, {
199
  token: 'npm_token'
200
});
201
```
202

203
## Error Conditions
204

205
### EPRIVATE Error
206

207
Thrown when attempting to publish a package marked as private.
208

209
```javascript
210
try {
211
  await publish({ name: 'pkg', version: '1.0.0', private: true }, tarballData, opts);
212
} catch (error) {
213
  if (error.code === 'EPRIVATE') {
214
    console.log('Remove the private field to publish');
215
  }
216
}
217
```
218

219
### EUNSCOPED Error
220

221
Thrown when attempting to restrict access to an unscoped package.
222

223
```javascript
224
try {
225
  await publish({ name: 'unscoped-pkg', version: '1.0.0' }, tarballData, {
226
    access: 'restricted'  // Error: unscoped packages cannot be restricted
227
  });
228
} catch (error) {
229
  if (error.code === 'EUNSCOPED') {
230
    console.log('Cannot restrict access to unscoped packages');
231
  }
232
}
233
```
234

235
### EBADSEMVER Error
236

237
Thrown when the package version is not valid semver.
238

239
```javascript
240
try {
241
  await publish({ name: 'pkg', version: 'not-semver' }, tarballData, opts);
242
} catch (error) {
243
  if (error.code === 'EBADSEMVER') {
244
    console.log('Invalid semver version');
245
  }
246
}
247
```
248

249
### EUSAGE Error
250

251
Thrown for provenance generation configuration errors.
252

253
```javascript
254
try {
255
  await publish(manifest, tarballData, {
256
    provenance: true,
257
    access: 'restricted'  // Error: provenance requires public access
258
  });
259
} catch (error) {
260
  if (error.code === 'EUSAGE') {
261
    console.log('Provenance requires public access');
262
  }
263
}
264
```