CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-libnpmpublish

Programmatic API for publishing and unpublishing npm packages with provenance support

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

publishing.mddocs/

Package Publishing

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

Capabilities

Publish Function

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

/**
 * Publishes a package to the npm registry
 * @param manifest - Parsed package.json manifest for the package being published
 * @param tarballData - Buffer containing the tarball data for the package
 * @param opts - Configuration options extending npm-registry-fetch options
 * @returns Promise resolving to response object with optional transparencyLogUrl
 */
function publish(manifest: Object, tarballData: Buffer, opts?: PublishOptions): Promise<PublishResult>;

interface PublishOptions {
  /** Access level for scoped packages: "public" or "restricted" (default: "public") */
  access?: 'public' | 'restricted';
  /** Tag to register the package with (default: "latest") */
  defaultTag?: string;
  /** Hashing algorithms for integrity generation (default: ["sha512"], always includes "sha1") */
  algorithms?: string[];
  /** Custom npm version string for _npmVersion field (identifies the publishing client) */
  npmVersion?: string;
  /** Enable automatic provenance generation in CI environments */
  provenance?: boolean;
  /** Path to external provenance statement file */
  provenanceFile?: string;
  /** Authentication token for registry */
  token?: string;
  /** Registry URL */
  registry?: string;
  /** Force publish even with validation warnings */
  force?: boolean;
}

interface PublishResult {
  /** Optional transparency log URL for provenance */
  transparencyLogUrl?: string;
}

Usage Examples:

const { publish } = require('libnpmpublish');
const fs = require('fs');

// Basic publishing
const manifest = {
  name: 'my-package',
  version: '1.0.0',
  description: 'My package description'
};

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

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

// Publishing with provenance in CI
await publish(manifest, tarballData, {
  token: 'npm_1234567890abcdef',
  provenance: true,
  access: 'public'
});

// Publishing scoped package with restricted access
const scopedManifest = {
  name: '@myorg/private-package',
  version: '1.0.0',
  description: 'Private organizational package'
};

await publish(scopedManifest, tarballData, {
  token: 'npm_1234567890abcdef',
  access: 'restricted'
});

// Publishing with custom tag and algorithms
await publish(manifest, tarballData, {
  token: 'npm_1234567890abcdef',
  defaultTag: 'beta',
  algorithms: ['sha512', 'sha256'],
  npmVersion: 'my-publish-tool@2.0.0'
});

Access Control

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

  • Public: Package is publicly accessible to all users
  • Restricted: Package access is limited to organization members (scoped packages only)
  • Unscoped packages: Always public, cannot be restricted
// Public scoped package
await publish(manifest, tarballData, {
  access: 'public',  // default
  token: 'npm_token'
});

// Restricted scoped package
await publish(manifest, tarballData, {
  access: 'restricted',
  token: 'npm_token'
});

Provenance Support

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

interface ProvenanceOptions {
  /** Enable automatic provenance generation (requires CI environment) */
  provenance?: boolean;
  /** Path to externally-generated provenance file */
  provenanceFile?: string;
}

Supported CI Environments:

  • GitHub Actions: Requires "write" access to "id-token" permission
  • GitLab CI: Requires SIGSTORE_ID_TOKEN with "sigstore" audience

Usage Examples:

// Automatic provenance in GitHub Actions
await publish(manifest, tarballData, {
  token: 'npm_token',
  provenance: true,
  access: 'public'  // Required for provenance
});

// External provenance file
await publish(manifest, tarballData, {
  token: 'npm_token',
  provenanceFile: './provenance.sigstore'
});

Integrity Generation

Generates cryptographic hashes for package verification using configurable algorithms.

interface IntegrityOptions {
  /** Hashing algorithms for integrity generation (default: ["sha512"]) */
  algorithms?: string[];
}

Supported Algorithms:

  • sha512 (default): Primary integrity hash
  • sha256: Additional integrity hash
  • sha1: Legacy shasum for compatibility

Usage Example:

await publish(manifest, tarballData, {
  token: 'npm_token',
  algorithms: ['sha512', 'sha256', 'sha1']
});

Tag Management

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

// Publish to latest tag (default)
await publish(manifest, tarballData, {
  token: 'npm_token'
  // defaultTag: 'latest' is implicit
});

// Publish to beta tag
await publish(manifest, tarballData, {
  token: 'npm_token',
  defaultTag: 'beta'
});

// Use manifest tag if specified
const manifestWithTag = {
  ...manifest,
  tag: 'alpha'
};
await publish(manifestWithTag, tarballData, {
  token: 'npm_token'
});

Error Conditions

EPRIVATE Error

Thrown when attempting to publish a package marked as private.

try {
  await publish({ name: 'pkg', version: '1.0.0', private: true }, tarballData, opts);
} catch (error) {
  if (error.code === 'EPRIVATE') {
    console.log('Remove the private field to publish');
  }
}

EUNSCOPED Error

Thrown when attempting to restrict access to an unscoped package.

try {
  await publish({ name: 'unscoped-pkg', version: '1.0.0' }, tarballData, {
    access: 'restricted'  // Error: unscoped packages cannot be restricted
  });
} catch (error) {
  if (error.code === 'EUNSCOPED') {
    console.log('Cannot restrict access to unscoped packages');
  }
}

EBADSEMVER Error

Thrown when the package version is not valid semver.

try {
  await publish({ name: 'pkg', version: 'not-semver' }, tarballData, opts);
} catch (error) {
  if (error.code === 'EBADSEMVER') {
    console.log('Invalid semver version');
  }
}

EUSAGE Error

Thrown for provenance generation configuration errors.

try {
  await publish(manifest, tarballData, {
    provenance: true,
    access: 'restricted'  // Error: provenance requires public access
  });
} catch (error) {
  if (error.code === 'EUSAGE') {
    console.log('Provenance requires public access');
  }
}

docs

index.md

publishing.md

unpublishing.md

tile.json