@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.

``bash
$ npm i @nodesecure/mama


or


$ yarn add @nodesecure/mama
`

Usage example

`ts
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

$3

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.

$3

Same as fromPackageJSON but using synchronous FS API.

$3

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.

`ts
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(locatedManifest.location);
}
`

$3

document is described by the following type:
`ts
import type {
PackumentVersion,
PackageJSON,
WorkspacesPackageJSON
} from "@nodesecure/npm-types";

type ManifestManagerDocument =
PackageJSON |
WorkspacesPackageJSON |
PackumentVersion;
`

And the options interface

`ts
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.

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

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

$3


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

$3

Return the type of the module

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

$3


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).

$3

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

`js
{
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

$3


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

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

$3

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

`json
{
"dependencies": {
"kleur": "1.0.0"
}
}
`

The above JSON will produce ["kleur"]

$3


Return true if workspaces property is present

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

$3

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

`ts
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
`

$3


Return true if version is starting with 0.x

$3

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...

`ts
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