@nodesecure/flags NPM

Requirements

Node.js v20 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/flags
# or
$ yarn add @nodesecure/flags

Usage example

import { getFlags, getManifest, eagerFetchFlagFile } from "@nodesecure/flags";

// Return a Set of flags title
const flags = getFlags();

// Return the manifest file
const manifest = getManifest();

const HTML = await eagerFetchFlagFile("hasBannedFile.html");

API

`getFlags(): Set<Flag>`

Returns a Set containing all available flag titles.

import { getFlags } from "@nodesecure/flags";

const flags = getFlags();
console.log(flags);
// Set(18) {
//   'hasExternalCapacity',
//   'hasWarnings',
//   'hasNativeCode',
//   'hasCustomResolver',
//   'hasNoLicense',
//   'hasMultipleLicenses',
//   'hasMinifiedCode',
//   'isDeprecated',
//   'hasManyPublishers',
//   'hasScript',
//   'hasIndirectDependencies',
//   'isGit',
//   'hasVulnerabilities',
//   'hasMissingOrUnusedDependency',
//   'isDead',
//   'hasBannedFile',
//   'isOutdated',
//   'hasDuplicate'
// }

`getManifest(): Record<string, FlagDescriptor>`

Returns the complete manifest object containing all flag descriptors.

import { getManifest } from "@nodesecure/flags";

const manifest = getManifest();
console.log(manifest.nativeCode);
// {
//   emoji: "🐲",
//   title: "hasNativeCode",
//   tooltipDescription: "The package uses and runs C++ or Rust N-API code"
// }

`getEmojiFromTitle(title: Flag): string`

Returns the emoji associated with a flag title. Returns "🔴" if the flag is not found.

import { getEmojiFromTitle } from "@nodesecure/flags";

console.log(getEmojiFromTitle("hasNativeCode")); // "🐲"
console.log(getEmojiFromTitle("unknownFlag")); // "🔴"

`getManifestEmoji(): IterableIterator<[string, string]>`

Returns an iterator of title, emoji pairs for all flags.

import { getManifestEmoji } from "@nodesecure/flags";

const emojiMap = Object.fromEntries(getManifestEmoji());
console.log(emojiMap);
// {
//   'hasExternalCapacity': '🌍',
//   'hasWarnings': '🚧',
//   'hasNativeCode': '🐲',
//   // ... all other flags
// }

File Operations (Node.js only)

`eagerFetchFlagFile(name: string): Promise<string>`

Asynchronously reads and returns the HTML content of a flag file.

import { eagerFetchFlagFile } from "@nodesecure/flags";

const htmlContent = await eagerFetchFlagFile("hasNativeCode");
console.log(htmlContent); // Returns the HTML documentation for the flag

`lazyFetchFlagFile(name: string): Readable`

Returns a Node.js Readable stream for a flag file, allowing for memory-efficient processing of large files.

import { lazyFetchFlagFile } from "@nodesecure/flags";

const stream = lazyFetchFlagFile("hasNativeCode");
stream.on('data', (chunk) => {
  console.log(chunk.toString());
});

Types

`FlagDescriptor`

interface FlagDescriptor {
  /** An emoji to visually identify the anomaly */
  emoji: string;
  /** Title (or name) of the flag */
  title: string;
  /** Short description/warning of the anomaly */
  tooltipDescription: string;
}

`Flag`

type Flag = keyof typeof FLAGS | (string & {});

Available Flags

Flag	Emoji	Description
`hasExternalCapacity`	🌍	The package uses at least one Node.js core dependency capable to establish communication outside of localhost
`hasWarnings`	🚧	The AST analysis has detected warnings (suspect import, unsafe regex ..)
`hasNativeCode`	🐲	The package uses and runs C++ or Rust N-API code
`hasCustomResolver`	💎	The package has dependencies who do not resolve on a registry (git, file, ssh etc..)
`hasNoLicense`	📜	The package does not have a license
`hasMultipleLicenses`	📚	The package has licenses in multiple locations (files or manifest)
`hasMinifiedCode`	🔬	The package has minified and/or uglified files
`isDeprecated`	⛔️	The package has been deprecated on NPM
`hasManyPublishers`	👥	The package has several publishers
`hasScript`	📦	The package has `post` and/or `pre` (un)install npm script
`hasIndirectDependencies`	🌲	The package has indirect dependencies
`isGit`	☁️	The package (project) is a git repository
`hasVulnerabilities`	🚨	The package has one or many vulnerabilities
`hasMissingOrUnusedDependency`	👀	A dependency is missing in package.json or a dependency is installed but never used
`isDead`	💀	The dependency has not received update from at least one year
`hasBannedFile`	⚔️	The project has at least one sensitive file
`isOutdated`	⌚️	The current package version is not equal to the package latest version
`hasDuplicate`	🎭	The package is also used somewhere else in the dependency tree but with a different version

Error Handling

lazyFetchFlagFile() and eagerFetchFlagFile() will throw a TypeError if no flag name is provided
lazyFetchFlagFile() and eagerFetchFlagFile() will throw an Error if the provided flag doesn't exist
Flag names can be provided with or without the .html extension