@nsec/core

Core Schemas, Configuration Loader, and Zero-Knowledge API Client for NullSec / ZVault

Overview • Installation • Modules • Usage Examples

Overview

@nsec/core is the foundational package providing:

• Zod Schemas & DTOs: Strict runtime type validation for projects, users, encrypted secrets payloads, service tokens, and invites.
• Config Loader: Hierarchical configuration discovery (nullsec.config.json, .nullsecrc, nsec.config.json, environment variables).
• NullSecApiClient: Complete HTTP client with cryptographic request signing (Ed25519), replay prevention, and timeout handling.
• Typed Errors: Standardized error classes across the NullSec ecosystem (ApiClientError, AuthenticationError, NotFoundError, ConfigError).

Installation

# With npm
npm install @nsec/core

# With pnpm
pnpm add @nsec/core

# With yarn
yarn add @nsec/core

Modules

1. Schemas (@nsec/core/schemas or root export)

Built using Zod for compile-time TypeScript inference and runtime payload validation:

| Schema | Purpose | |---|---| | NullSecConfigSchema | Configuration file structure (projectId, serverUrl, defaultEnv, etc.) | | ProjectSchema | Project entities, environments, members, and access roles | | UserSchema | User identity entity with public keys (Ed25519 signing, RSA encryption) | | EncryptedSecretsPayloadSchema | Base64 AES-256-GCM ciphertext, IV, and auth tag | | EncryptedProjectKeySchema | Wrapped Master Project Key (RSA-OAEP-4096 or AES-256-GCM) | | ServiceTokenSchema | CI/CD automation token metadata and token prefix validation | | InviteTokenSchema | Single-use registration invite tokens |

2. Configuration Loader (loadConfig, findConfigFile)

Resolves configurations by searching up the directory tree and merging environment variable overrides:

Search priority:

1. Explicit function overrides
2. Environment variables (NULLSEC_PROJECT_ID, NULLSEC_SERVER_URL, NSEC_*, ZVAULT_*)
3. Nearest project config file (nullsec.config.json, .nullsecrc.json, nsec.config.json, etc.)

import { loadConfig, findConfigFile } from '@nsec/core';

// Search up from current directory and parse validated config
const config = await loadConfig();
console.log(`Connected to project: ${config.projectId} at ${config.serverUrl}`);

3. API Client (NullSecApiClient)

Performs authenticated zero-knowledge HTTP communication with the NullSec server. Requests are signed using the user's Ed25519 private key or authenticated via CI/CD Bearer service tokens.

import { NullSecApiClient } from '@nsec/core';

// 1. Initialized with Developer Identity Keys
const client = new NullSecApiClient({
  serverUrl: 'https://vault.internal.net',
  signingKeys: {
    privateKey: userSigningPrivateKeyPem,
    publicKey: userSigningPublicKeyPem
  },
  timeoutMs: 15_000
});

// Fetch encrypted secrets payload for environment
const secretsResponse = await client.fetchSecrets('my-app', 'production');
// {
//   secrets: { ciphertext: '...', iv: '...', tag: '...', version: 1 },
//   projectKey: { encryptedKey: '...', algorithm: 'RSA-OAEP-4096' }
// }

// 2. Initialized with CI/CD Service Token
const ciClient = new NullSecApiClient({
  serverUrl: 'https://vault.internal.net',
  serviceToken: 'zv_st_production_a9c...'
});

const ciSecretsResponse = await ciClient.fetchSecrets('my-app', 'production');

Error Handling

@nsec/core exports domain-specific error classes for error matching and handling:

import {
  ApiClientError,
  AuthenticationError,
  NotFoundError,
  ConfigError
} from '@nsec/core';

try {
  await client.getProject('unknown-id');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.error('Project does not exist');
  } else if (err instanceof AuthenticationError) {
    console.error('Cryptographic signature failed verification or user unauthorized');
  } else if (err instanceof ApiClientError) {
    console.error(`API request failed with status: ${err.statusCode}`);
  }
}

License

MIT © NullSec / zVault Contributors