@parmana/shared

Domain types, config loading, and error classes every other package depends on. No business logic of its own.

[AVAILABLE]. packages/shared. The foundation package: every other Parmana package imports from here, this package imports from none of them.

Purpose

Canonical TypeScript types for every artifact in the trust chain (Authority through ExecutionTrustRecord), the loadConfig() environment-variable reader, and a shared error class hierarchy so every package throws recognizable, instanceof-checkable errors rather than plain Error.

Install

npm install @parmana/shared

Key exports

Domain types, all [AVAILABLE]

Export	What it is
Authority	Who is empowered to authorize execution
Authorization	A grant, with purpose and optional expiry
Intent	The specific action, target, and parameters requested
BusinessTransaction	The immutable input to policy evaluation
Decision	A policy’s outcome, APPROVED or REJECTED, plus reason and evaluated signals
Execution	What actually happened: status, mode, evidence
ExecutionEvidence	Action, target, parameters, success, and an open attributes bag
ExecutionTrustRecord	The signed, append-only aggregate, see Execution trust records
SignedExecutionAuthorization, ExecutionAuthorizationPayload	The signed envelope, see Execution authorization
Signature	{ algorithm, keyId, value, signedAt }
Verification, Receipt, Override	Append-only record types on the trust record
PolicyReference	{ name, version, schemaVersion }

Config

export function loadConfig(): Readonly<Config>;

Reads process.env fresh on every call, no caching, no memoization. Config covers storage provider, key directory, primarySignatureProvider / secondarySignatureProvider, hash provider, and policy directory. See Deploy patterns for the full environment variable checklist.

Errors, all [AVAILABLE]

ParmanaError is the common base class. Notable subclasses: BusinessTransactionNotFoundError, PolicyNotFoundError, AuthorityRequiredError, AuthorizationRequiredError, IntentRequiredError, DecisionNotApprovedError, ForbiddenError, UnauthorizedError, ConflictError, ValidationError, VerificationFailedError, TrustChainValidationError, ReceiptGenerationError, OverrideNotAllowedError. packages/api/src/middleware/error-handler.ts checks several of these by instanceof, see API error reference for exactly which ones actually reach a distinct HTTP status today.

Minimal example

import { loadConfig, type BusinessTransaction } from "@parmana/shared";

const config = loadConfig();
console.log(config.crypto.primarySignatureProvider); // "ed25519" by default

Next

Execution trust records

The domain type this package’s ExecutionTrustRecord implements.

@parmana/crypto

Where these types get hashed and signed.