@nodesecure/mama

@nodesecure/mama

Manifest Manager

Requirements

• Node.js v24 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @nodesecure/mama
# or
$ yarn add @nodesecure/mama

Usage example

import { ManifestManager } from "@nodesecure/mama";

const mama = await ManifestManager.fromPackageJSON(
  process.cwd()
);
console.log(mama.document);
console.log(mama.integrity);

Utils

This package exports a set of standalone utilities that are internally used by the ManifestManager class, but may also be useful independently for various tasks:

• packageJSONIntegrityHash
• parseNpmSpec
• inspectModuleType
• scanLockFiles

ManifestManager API

(static) fromPackageJSON(locationOrManifest: string | ManifestManager): Promise< ManifestManager >

Load a ManifestManager from a given location or return the instance if one is provided.

The locationOrManifest parameter can either be a string (representing a path) or a ManifestManager instance.

• If it is a string, it can either be a full path to a package.json or the path to the directory where one is located.
• If it is a ManifestManager instance, the method will return the instance directly.

[!NOTE] When a location string is provided, it is automatically dispatched to the ManifestManager constructor options.

(static) fromPackageJSONSync(locationOrManifest: string | ManifestManager): ManifestManager

Same as fromPackageJSON but using synchronous FS API.

(static) isLocated(mama: ManifestManager): mama is LocatedManifestManager

A TypeScript type guard to check if a ManifestManager instance has a location. This is particularly useful when working with manifests that may or may not have been loaded from the filesystem.

When the type guard is successful, the location property is available on the instance.

import { ManifestManager, type LocatedManifestManager } from "@nodesecure/mama";
import { expectType } from "tsd";

const locatedManifest = new ManifestManager(
  { name: "test", version: "1.0.0" },
  { location: "/tmp/path" }
);

if (ManifestManager.isLocated(locatedManifest)) {
  // locatedManifest is now of type LocatedManifestManager
  expectType<string>(locatedManifest.location);
}

constructor(document: ManifestManagerDocument, options?: ManifestManagerOptions)

document is described by the following type:

import type {
  PackumentVersion,
  PackageJSON,
  WorkspacesPackageJSON
} from "@nodesecure/npm-types";

type ManifestManagerDocument =
  PackageJSON |
  WorkspacesPackageJSON |
  PackumentVersion;

And the options interface

export interface ManifestManagerOptions {
  /**
   * Optional absolute location (directory) to the manifest
   */
  location?: string;
}

Default values are injected if they are not present in the document. This behavior is necessary for the correct operation of certain functions, such as integrity recovery.

{
  dependencies: {},
  devDependencies: {},
  scripts: {},
  gypfile: false
}

[!NOTE] document is deep cloned (there will no longer be any reference to the object supplied as an argument)

getEntryFiles(): IterableIterator< string >

Deeply extract entry files from package main and Node.js exports fields.

moduleType

Return the type of the module

type PackageModuleType = "dts" | "faux" | "dual" | "esm" | "cjs";

spec

Return the NPM specification (which is the combinaison of name@version).

[!CAUTION] This property may not be available for Workspaces (if 'name' or 'version' properties are missing, it will throw an error).

integrity

Return an integrity hash (which is a string) of the following properties:

{
  name,
  version,
  dependencies,
  license: license ?? "NONE",
  scripts
}

If dependencies and scripts are missing, they are defaulted to an empty object {}

[!CAUTION] This is not available for Workspaces

author

Return the author parsed as a Contact (or null if the property is missing).

interface Contact {
  email?: string;
  url?: string;
  name: string;
}

dependencies and devDependencies

Return the (dev) dependencies as an Array (of string)

{
  "dependencies": {
    "kleur": "1.0.0"
  }
}

The above JSON will produce ["kleur"]

isWorkspace

Return true if workspaces property is present

[!NOTE] Workspace are described by the interface WorkspacesPackageJSON (from @nodesecure/npm-types)

location

A string representing the absolute path to the manifest file's directory, if it was provided in the constructor options. Otherwise, it is undefined.

const mama = new ManifestManager(
  { name: "test", version: "1.0.0" },
  { location: "/home/user/my-project/package.json" }
);

console.log(mama.location); //-> /home/user/my-project

hasZeroSemver

Return true if version is starting with 0.x

flags

Since we've created this package for security purposes, the instance contains various flags indicating threats detected in the content:

• isNative: Contain an identified native package to build or provide N-API features like node-gyp.
• hasUnsafeScripts: Contain unsafe scripts like install, preinstall, postinstall...

import assert from "node:assert";

const mama = new ManifestManager({
  name: "hello",
  version: "1.0.0",
  scripts: {
    postinstall: "node malicious.js"
  }
});

assert.ok(mama.flags.hasUnsafeScripts);

The flags property is sealed (It is not possible to extend the list of flags)

[!IMPORTANT] Read more about unsafe scripts here