permission-gap-detector 0.0.0-stage → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.0.2
+
+- Reject control characters in route paths before rendering reports.
+- Accept UTF-8 BOM JSON files and literal filenames after `--`.
+- Add command-specific help with documented exit codes.
+- Expand regression coverage to 27 tests and include a clean route example.
+
+
+## 1.0.1
+
+- Keep the distribution focused on source code, usage examples, and package documentation.
+- Simplify the README and published file list.
+
+## 1.0.0
+
+- Add missing and invalid permission checks.
+- Add duplicate and conflicting policy detection.
+- Add summary counts and declaration coverage.
+- Add CommonJS API and CLI with JSON output and exit codes.
+- Add 20 automated tests and usage examples.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya030207
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,236 @@
-# Temporary Holding Version
+# Permission Gap Detector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, dependency-free CommonJS Node.js package that checks **declared API route permissions**.
+
+## Problem statement
+
+While building an Express REST API, a developer can forget to specify who should access a route. A route list makes these decisions visible. This package finds missing or inconsistent declarations so they can be reviewed.
+
+It does not inspect Express middleware or prove that an application is secure.
+
+## Features
+
+- Detect missing permissions and unsupported permission values.
+- Support `public`, `authenticated`, and `admin` policies.
+- Detect repeated method/path pairs and conflicting valid policies.
+- Return structured findings and permission declaration coverage.
+- Read route lists from JSON using a simple CLI.
+
+## Installation
+
+Requires Node.js 20 or newer and npm. No external dependencies.
+
+Install from npm:
+
+```bash
+npm install permission-gap-detector
+```
+
+Alternatively, install directly from GitHub:
+
+```bash
+npm install github:Aditya030207/npm-package-project
+```
+
+Or run `npm pack` in this repository and install the resulting archive in another project:
+
+```bash
+npm install /absolute/path/to/permission-gap-detector-1.0.2.tgz
+```
+
+## Basic usage
+
+```js
+const { auditRoutes } = require('permission-gap-detector');
+
+const routes = [
+  { method: 'GET', path: '/products', access: 'public' },
+  { method: 'DELETE', path: '/products/:id' }
+];
+
+const result = auditRoutes(routes);
+console.log(result.summary);
+console.log(result.findings.missingPermissions);
+// [{ index: 1, method: 'DELETE', path: '/products/:id' }]
+```
+
+Maintain this route list alongside your Express routes. The package does not automatically discover routes.
+
+## Route format and validation
+
+Input is an array of ordinary route objects. Each object needs:
+
+| Field | Accepted values |
+| --- | --- |
+| `method` | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, CONNECT, TRACE; case-insensitive |
+| `path` | A string starting with `/`, without whitespace or control characters |
+| `access` | Exactly `public`, `authenticated`, or `admin` |
+
+`public` allows anyone; `authenticated` requires a logged-in user; `admin` requires administrator access. These are declarations, not enforcement.
+
+Absent, undefined, null, empty, and whitespace-only access values are missing. Other unsupported values are invalid permissions. Invalid route objects, methods, and paths are reported as invalid routes and excluded from other checks. Additional fields are ignored. Methods are normalized to uppercase without changing the input. Paths are compared exactly: `/users`, `/Users`, `/users/`, and parameter names are distinct.
+
+## API
+
+All four functions accept a route array and leave it unchanged. A non-array argument throws `TypeError`. Invalid entries inside an array are reported by `auditRoutes` instead of throwing.
+
+### `auditRoutes(routes)`
+
+Returns `{ summary, findings, hasIssues }`.
+
+`summary` contains:
+
+| Field | Meaning |
+| --- | --- |
+| `totalRoutes` | All submitted definitions, including invalid entries |
+| `validPermissions` | Structurally valid definitions with a supported access value |
+| `missingPermissions` | Valid route structures with missing access |
+| `invalidPermissions` | Valid route structures with unsupported access |
+| `invalidRoutes` | Invalid route structures |
+| `duplicateRoutes` | Extra definitions beyond the first in each repeated method/path group |
+| `conflictingRoutes` | Method/path groups with at least two distinct supported policies |
+| `coveragePercentage` | Valid permissions divided by total definitions, multiplied by 100, rounded to one decimal |
+
+The four permission/validation categories sum to `totalRoutes`. An empty array has 0% coverage because no declarations were checked. Duplicates and conflicts overlap with these categories and must not be added to them. Three copies of one route count as two duplicates. A conflicting group counts once. Valid policies on duplicates still count toward declaration coverage: **100% coverage can coexist with conflicts and does not mean secure**.
+
+`findings` contains five arrays:
+
+- `missingPermissions`: `{ index, method, path }`.
+- `invalidPermissions`: `{ index, method, path, access }`.
+- `invalidRoutes`: `{ index, message }`.
+- `duplicateRoutes`: `{ method, path, indices, extraDefinitions }`.
+- `conflictingPermissions`: `{ method, path, indices, permissions }`.
+
+Indices are zero-based positions in the original array. Conflict indices include all definitions in that group; `permissions` lists its distinct supported values. Missing and invalid policies do not themselves create conflicts. `hasIssues` is true when any findings array is nonempty.
+
+### `findMissingPermissions(routes)`
+
+Returns the `missingPermissions` findings array.
+
+### `findDuplicateRoutes(routes)`
+
+Returns the `duplicateRoutes` findings array, one object per repeated group.
+
+### `findConflictingPermissions(routes)`
+
+Returns the `conflictingPermissions` findings array, one object per conflicting group.
+
+The three convenience functions return only their named findings. Use `auditRoutes` to see validation errors as well.
+
+## CLI usage
+
+Run directly from npm:
+
+```bash
+npx permission-gap-detector check routes.json
+```
+
+After installation into a project:
+
+```bash
+npx --no-install permission-gap check routes.json
+npx --no-install permission-gap check routes.json --json
+```
+
+For a direct shell command, globally install the package with `npm install -g permission-gap-detector` then run `permission-gap check routes.json`. Both binary names point to the same CLI.
+
+From this repository:
+
+```bash
+node bin/cli.js check examples/routes.json
+node bin/cli.js check examples/routes.json --json
+node bin/cli.js --help
+node bin/cli.js check --help
+node bin/cli.js --version
+```
+
+UTF-8 files may begin with a byte order mark (BOM). Files must contain a JSON array, not an object wrapping the array. Paths are relative to the current working directory; quote paths containing spaces. Use `permission-gap check --json -- -routes.json` for a filename beginning with a dash; options must come before `--`. Exit codes: **0** = no findings, **1** = audit findings, **2** = invalid command, unreadable file, malformed JSON, or non-array input. Human-readable failures go to stderr. With `--json`, failures are `{ "error": "message" }` on stdout.
+
+## Example output
+
+Running the included six-definition example produces:
+
+```text
+==================================
+     PERMISSION GAP DETECTOR
+==================================
+
+Total Routes Checked: 6
+Valid Permissions: 5
+Missing Permissions: 1
+Invalid Permissions: 0
+Invalid Route Definitions: 0
+Duplicate Routes (extra definitions): 2
+Conflicting Policies (route groups): 1
+
+Permission Coverage: 83.3%
+
+Issues Found:
+[WARNING] DELETE /products/:id: Missing permission declaration (index 2).
+[WARNING] GET /products: Duplicate route definition (indices 0, 3).
+[WARNING] GET /admin: Duplicate route definition (indices 4, 5).
+[ERROR] GET /admin: Conflicting permissions: admin, public.
+
+==================================
+Audit Complete
+==================================
+```
+
+The example intentionally has issues and exits with code 1.
+
+For a complete set of consistent declarations, run:
+
+```bash
+node bin/cli.js check examples/clean-routes.json
+```
+
+This example uses all three supported permissions, reports 100% declaration coverage with no findings, and exits with code 0. Compare it with `examples/routes.json` to see how missing and conflicting declarations change the result. Neither result verifies middleware enforcement.
+
+## Development and testing
+
+```bash
+git clone https://github.com/Aditya030207/npm-package-project.git
+cd npm-package-project
+npm ci
+npm test
+node examples/basic.js
+npm pack --dry-run
+```
+
+The 27 automated tests use `node:test` and strict assertions. They cover valid policies, input validation, missing permissions, duplicates, conflicts, counting, immutability, reports, and CLI behavior with real temporary files and child processes.
+
+## Source structure
+
+```text
+npm-package-project/
+├── src/
+│   ├── index.js             # Four public exports
+│   ├── auditRoutes.js       # Combine checks and calculate summary
+│   ├── checkPermissions.js  # Validate input and access policies
+│   ├── checkDuplicates.js   # Group routes and find conflicts
+│   └── generateReport.js    # Format readable terminal output
+├── bin/cli.js               # Arguments, JSON file reading, exit codes
+├── tests/package.test.js    # API and CLI tests
+├── examples/
+│   ├── basic.js
+│   ├── routes.json
+│   └── clean-routes.json
+├── package.json
+├── package-lock.json
+├── README.md
+├── CHANGELOG.md
+├── LICENSE
+└── .gitignore
+```
+
+## Limitations
+
+This audits only supplied route declarations. It does not scan source code, discover Express routes, execute middleware, validate tokens, enforce access rules, or assess application security. It does not infer route equivalence, inherited policies, Express mount paths, or wildcard matching. A public policy on a sensitive route is only detected as a conflict if another definition declares a different valid policy. Keep route declarations synchronized with the actual application.
+
+## Contributing
+
+Open an issue describing a problem or propose a small change. Add a meaningful test for changed behavior and run `npm test`. Keep the project simple and dependency-free.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const { auditRoutes } = require('../src');
+const generateReport = require('../src/generateReport');
+const { version } = require('../package.json');
+const args = process.argv.slice(2);
+// Arguments after -- are literal filenames, even when they begin with a dash.
+const separator = args.indexOf('--');
+const options = separator === -1 ? args : args.slice(0, separator);
+const filenames = separator === -1 ? [] : args.slice(separator + 1);
+const json = options.includes('--json');
+const usage = 'Usage: permission-gap check <routes.json> [--json]\n       permission-gap check [--json] -- <filename>\nOptions: --help, --version, --json\nExit codes: 0 = no findings, 1 = audit findings, 2 = input error';
+
+try {
+  if ((args.length === 1 && args[0] === '--help') ||
+      (args.length === 2 && args[0] === 'check' && args[1] === '--help')) {
+    console.log(usage);
+  } else if (args.length === 1 && args[0] === '--version') {
+    console.log(version);
+  } else {
+    const positional = [...options.filter(arg => arg !== '--json'), ...filenames];
+    const unknownOption = options.some(arg => arg.startsWith('-') && arg !== '--json');
+    if (positional.length !== 2 || positional[0] !== 'check' || unknownOption || options.filter(arg => arg === '--json').length > 1) {
+      throw new Error(usage);
+    }
+    let content;
+    try { content = fs.readFileSync(positional[1], 'utf8'); }
+    catch { throw new Error(`Cannot read file: ${positional[1]}`); }
+    let routes;
+    try { routes = JSON.parse(content.replace(/^\uFEFF/, '')); }
+    catch { throw new Error(`Invalid JSON in file: ${positional[1]}`); }
+    const result = auditRoutes(routes);
+    console.log(json ? JSON.stringify(result, null, 2) : generateReport(result));
+    process.exitCode = result.hasIssues ? 1 : 0;
+  }
+} catch (error) {
+  if (json) console.log(JSON.stringify({ error: error.message }));
+  else console.error(`Error: ${error.message}`);
+  process.exitCode = 2;
+}

package/examples/basic.js

@@ -0,0 +1,3 @@
+const { auditRoutes } = require('../src');
+const routes = require('./routes.json');
+console.log(JSON.stringify(auditRoutes(routes), null, 2));

package/examples/clean-routes.json

@@ -0,0 +1,17 @@
+[
+  {
+    "method": "GET",
+    "path": "/products",
+    "access": "public"
+  },
+  {
+    "method": "POST",
+    "path": "/products",
+    "access": "authenticated"
+  },
+  {
+    "method": "DELETE",
+    "path": "/products/:id",
+    "access": "admin"
+  }
+]

package/examples/routes.json

@@ -0,0 +1,31 @@
+[
+  {
+    "method": "GET",
+    "path": "/products",
+    "access": "public"
+  },
+  {
+    "method": "POST",
+    "path": "/products",
+    "access": "authenticated"
+  },
+  {
+    "method": "DELETE",
+    "path": "/products/:id"
+  },
+  {
+    "method": "GET",
+    "path": "/products",
+    "access": "public"
+  },
+  {
+    "method": "GET",
+    "path": "/admin",
+    "access": "admin"
+  },
+  {
+    "method": "GET",
+    "path": "/admin",
+    "access": "public"
+  }
+]

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "permission-gap-detector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "Check declared API route permissions for missing policies, duplicates, and conflicts.",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "bin": {
+    "permission-gap": "bin/cli.js",
+    "permission-gap-detector": "bin/cli.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "examples/",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "permissions",
+    "routes",
+    "express",
+    "audit",
+    "cli"
+  ],
+  "author": "Aditya030207",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aditya030207/npm-package-project.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Aditya030207/npm-package-project/issues"
+  },
+  "homepage": "https://github.com/Aditya030207/npm-package-project#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/auditRoutes.js

@@ -0,0 +1,25 @@
+const { validateRoutes, checkPermissions } = require('./checkPermissions');
+const checkDuplicates = require('./checkDuplicates');
+
+function auditRoutes(routes) {
+  const { validRoutes, invalidRoutes } = validateRoutes(routes);
+  const { validPermissions, missingPermissions, invalidPermissions } = checkPermissions(validRoutes);
+  const { duplicateRoutes, conflictingPermissions } = checkDuplicates(validRoutes);
+  const findings = { missingPermissions, invalidPermissions, invalidRoutes, duplicateRoutes, conflictingPermissions };
+  return {
+    summary: {
+      totalRoutes: routes.length,
+      validPermissions,
+      missingPermissions: missingPermissions.length,
+      invalidPermissions: invalidPermissions.length,
+      invalidRoutes: invalidRoutes.length,
+      duplicateRoutes: duplicateRoutes.reduce((sum, group) => sum + group.extraDefinitions, 0),
+      conflictingRoutes: conflictingPermissions.length,
+      coveragePercentage: routes.length === 0 ? 0 : Math.round(validPermissions / routes.length * 1000) / 10
+    },
+    findings,
+    hasIssues: Object.values(findings).some(items => items.length > 0)
+  };
+}
+
+module.exports = auditRoutes;

package/src/checkDuplicates.js

@@ -0,0 +1,26 @@
+const { ACCESS_TYPES } = require('./checkPermissions');
+
+function checkDuplicates(routes) {
+  const groups = new Map();
+  for (const route of routes) {
+    const key = `${route.method} ${route.path}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(route);
+  }
+  const duplicateRoutes = [];
+  const conflictingPermissions = [];
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const { method, path } = group[0];
+    const indices = group.map(route => route.index);
+    duplicateRoutes.push({ method, path, indices, extraDefinitions: group.length - 1 });
+    // Only supported policies can conflict; other values have their own findings.
+    const permissions = [...new Set(group.map(route => route.access).filter(access => ACCESS_TYPES.includes(access)))];
+    if (permissions.length > 1) {
+      conflictingPermissions.push({ method, path, indices, permissions });
+    }
+  }
+  return { duplicateRoutes, conflictingPermissions };
+}
+
+module.exports = checkDuplicates;

package/src/checkPermissions.js

@@ -0,0 +1,38 @@
+const ACCESS_TYPES = ['public', 'authenticated', 'admin'];
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'CONNECT', 'TRACE'];
+
+function validateRoutes(routes) {
+  if (!Array.isArray(routes)) throw new TypeError('Routes must be an array.');
+  const validRoutes = [];
+  const invalidRoutes = [];
+  for (let index = 0; index < routes.length; index++) {
+    const route = routes[index];
+    if (!route || typeof route !== 'object' || Array.isArray(route) ||
+        typeof route.method !== 'string' || !METHODS.includes(route.method.toUpperCase()) ||
+        typeof route.path !== 'string' || !route.path.startsWith('/') || /[\s\x00-\x1f\x7f-\x9f]/.test(route.path)) {
+      invalidRoutes.push({ index, message: 'Expected an object with a supported HTTP method and a path starting with / without whitespace or control characters.' });
+      continue;
+    }
+    validRoutes.push({ index, method: route.method.toUpperCase(), path: route.path, access: route.access });
+  }
+  return { validRoutes, invalidRoutes };
+}
+
+function checkPermissions(routes) {
+  const missingPermissions = [];
+  const invalidPermissions = [];
+  let validPermissions = 0;
+  for (const route of routes) {
+    const { index, method, path, access } = route;
+    if (access === undefined || access === null || (typeof access === 'string' && access.trim() === '')) {
+      missingPermissions.push({ index, method, path });
+    } else if (!ACCESS_TYPES.includes(access)) {
+      invalidPermissions.push({ index, method, path, access });
+    } else {
+      validPermissions++;
+    }
+  }
+  return { validPermissions, missingPermissions, invalidPermissions };
+}
+
+module.exports = { validateRoutes, checkPermissions, ACCESS_TYPES };

package/src/generateReport.js

@@ -0,0 +1,21 @@
+function generateReport(result) {
+  const { summary: s, findings: f } = result;
+  const lines = [
+    '==================================', '     PERMISSION GAP DETECTOR', '==================================', '',
+    `Total Routes Checked: ${s.totalRoutes}`, `Valid Permissions: ${s.validPermissions}`,
+    `Missing Permissions: ${s.missingPermissions}`, `Invalid Permissions: ${s.invalidPermissions}`,
+    `Invalid Route Definitions: ${s.invalidRoutes}`, `Duplicate Routes (extra definitions): ${s.duplicateRoutes}`,
+    `Conflicting Policies (route groups): ${s.conflictingRoutes}`, '',
+    `Permission Coverage: ${s.coveragePercentage}%`, '', 'Issues Found:'
+  ];
+  for (const route of f.missingPermissions) lines.push(`[WARNING] ${route.method} ${route.path}: Missing permission declaration (index ${route.index}).`);
+  for (const route of f.invalidPermissions) lines.push(`[ERROR] ${route.method} ${route.path}: Invalid permission; use public, authenticated, or admin (index ${route.index}).`);
+  for (const route of f.invalidRoutes) lines.push(`[ERROR] Index ${route.index}: ${route.message}`);
+  for (const route of f.duplicateRoutes) lines.push(`[WARNING] ${route.method} ${route.path}: Duplicate route definition (indices ${route.indices.join(', ')}).`);
+  for (const route of f.conflictingPermissions) lines.push(`[ERROR] ${route.method} ${route.path}: Conflicting permissions: ${route.permissions.join(', ')}.`);
+  if (!result.hasIssues) lines.push('No issues found.');
+  lines.push('', '==================================', 'Audit Complete', '==================================');
+  return lines.join('\n');
+}
+
+module.exports = generateReport;

package/src/index.js

@@ -0,0 +1,15 @@
+const auditRoutes = require('./auditRoutes');
+
+function findMissingPermissions(routes) {
+  return auditRoutes(routes).findings.missingPermissions;
+}
+
+function findDuplicateRoutes(routes) {
+  return auditRoutes(routes).findings.duplicateRoutes;
+}
+
+function findConflictingPermissions(routes) {
+  return auditRoutes(routes).findings.conflictingPermissions;
+}
+
+module.exports = { auditRoutes, findMissingPermissions, findDuplicateRoutes, findConflictingPermissions };