tomalib

Environment-independent workspace content policy utilities. The package helps Node.js applications decide whether a relative file path is excluded, detect potential secrets without returning their values, and calculate SHA-256 digests for integrity checks.

Installation

npm install tomalib

Usage

JavaScript

import { WorkspaceContentPolicy, sha256 } from 'tomalib';

const policy = new WorkspaceContentPolicy();
const assessment = policy.assess('src/auth.ts', 'export function authenticate() {}');

if (assessment.decision === 'allow') {
  console.log(sha256('content to store'));
}

TypeScript

import { WorkspaceContentPolicy, type ContentAssessment } from 'tomalib';

const policy = new WorkspaceContentPolicy({
  additionalExcludedPaths: [/^internal\//]
});
const assessment: ContentAssessment = policy.assess('internal/debug.ts');

CLI

The CLI checks the health of a running API endpoint. It does not scan or upload files.

npx tomalib
npx tomalib health
npx tomalib health --url https://api.codeforge.sysdak.com

By default, health checks the deployed production API. Use --url http://127.0.0.1:8080 for the local Docker API.

Temporary Archive Transfer

Set the same secret values on both laptops. TOMALIB_API_TOKEN authorizes the API and TOMALIB_ARCHIVE_KEY encrypts archives locally (legacy CODEFORGE_* environment variables are also supported). Never store either in source code.

$env:TOMALIB_API_TOKEN = "f8355d8cf10b15306176f64b2c90a3b4b3ae6eb2d95059e9068f3f2a1bc58c32"
$env:TOMALIB_ARCHIVE_KEY = "f8355d8cf10b15306176f64b2c90a3b4b3ae6eb2d95059e9068f3f2a1bc58c32"
npx tomalib upload --file "D:\workspace.zip"
npx tomalib download --archive "archive-id" --output "D:\restored.zip"

Archives are encrypted with AES-256-GCM before direct Vercel Blob upload, limited to 50 MiB before encryption, expire after 30 minutes, and are deleted after a successful download.

API

WorkspaceContentPolicy

• new WorkspaceContentPolicy(options?): creates a stateless policy. Default exclusions include .env*, private-key file types, credentials/, secrets/, .git/, dependency folders, and common build output.
• isPathExcluded(relativePath): returns whether a relative path matches the exclusion policy.
• hasPotentialSecret(content): returns whether content resembles a credential or private key. It never returns matched secret text.
• assess(relativePath, content?): returns { decision: 'allow' | 'exclude' | 'block', reason? }.

sha256(content)

Returns the lowercase hexadecimal SHA-256 digest for a UTF-8 string or Uint8Array.

Configuration

WorkspaceContentPolicy accepts optional additionalExcludedPaths and additionalSecretPatterns arrays of regular expressions. These rules supplement, rather than remove, the secure defaults.

Error Handling

Path methods require a non-empty string. Content scanning requires a string. sha256 accepts only strings and Uint8Array values. Invalid values throw TypeError.

Compatibility

Node.js 18 or later. The package is ESM-only and has no runtime dependencies.

Development

npm install
npm run build
npm test
npm pack --dry-run

Publishing

npm login
npm publish

Publishing is intentionally manual.