attepack

Attepack

Attepack is a shared library of packet envelope primitives, schema contracts, and error packet normalization routines for tool ecosystems.

Purpose

Across a tool ecosystem, public tools such as Remogram, Skillpress, and ReleasePress exchange structured JSON packets (e.g. remogram.forge_facts.v1, skillpress.capability_manifest.v1, release.evidence_manifest.v1, consumer.audit_view_model.v1). Attepack standardizes these packet envelopes and error structures to eliminate duplicate parsing and prevent schema drift.

Modules

Module	Purpose
attepack	Primary entrypoint exporting envelope validation and error packet constructors
attepack/envelope	Enforces packet envelope validation (type, schema_version, observed_at, ok)
attepack/errors	Known error codes plus buildFormattedError for stable { code, message, details? } shapes
attepack/sanitize	Redacts sensitive text from error messages and allowlists error detail fields
attepack/receipts	Builds and validates mutation receipts bound to SHA-256 digests
attepack/diagnostics	Builds diagnostic events and validates fail-closed sink command argv
attepack/cli-emit	Fail-closed CLI JSON emit helper: flush-before-exit and a typed too-large error
attepack/evidence-protocol	Validates neutral producer-native evidence packet conformance without product-specific schemas
attepack/dependency-pins	Asserts installed security packages match package-lock.json across nested node_modules

Install

npm install attepack

Quick Start

import { validatePacketEnvelope, buildErrorPacket } from 'attepack';

const envelope = validatePacketEnvelope({
  type: 'attepack.sample.v1',
  schema_version: 1,
  observed_at: new Date().toISOString(),
  ok: true
});

Error formatting:

import { ATTEPACK_ERROR_CODES, buildFormattedError } from 'attepack/errors';

const error = buildFormattedError(
  ATTEPACK_ERROR_CODES.INVALID_ARGS,
  'Missing required field',
  { field: 'schema_version' }
);
// { code: 'invalid_args', message: 'Missing required field', details: { field: 'schema_version' } }

Message and details sanitization:

import { sanitizeErrorMessage, sanitizeErrorDetails } from 'attepack/sanitize';

const message = sanitizeErrorMessage('failed under a local home path');
const details = sanitizeErrorDetails({
  field: 'credential_field',
  reason: 'rejected',
  value: 'redacted-before-call'
});

Mutation receipts:

import { buildMutationReceipt } from 'attepack/receipts';

const digest = 'a'.repeat(64);
const receipt = buildMutationReceipt({
  mutationKind: 'cr_merged',
  identityDigest: digest,
  intentDigest: digest,
  providerId: 'gitea-api',
  remoteName: 'origin',
  repoId: 'example/tool'
});

Diagnostic events:

import { buildDiagnosticEvent } from 'attepack/diagnostics';

const event = buildDiagnosticEvent({
  tool: 'example-tool',
  command: 'doctor',
  failureClass: 'config_invalid',
  details: { field: 'baseUrl' }
});

Neutral Evidence Protocol

Producer tools should validate their own native packets against the neutral evidence protocol instead of importing downstream product schemas or goldens. Downstream products may consume, compose, archive, report, and evaluate policy over those packets; they are not the protocol owner.

import { validateNeutralEvidencePacket } from 'attepack/evidence-protocol';

validateNeutralEvidencePacket({
  type: 'remogram.forge_facts.v1',
  schema_version: 1,
  ok: true,
  authority_role: 'authoritative'
});

Attepack rejects legacy producer-section fields and the atteway product namespace by default. Override with forbiddenProductNamespaces when a caller needs a different forbid-list.

The same module also owns neutral, product-independent evidence binding mechanics for guidance-lifecycle packets. Producers can use these primitives to bind packets to public repository identity, exact candidate base/head SHAs, merged source commits, capability-contract digests, source-artifact digests, parent evidence digests, multi-target receipt summaries, safe relative evidence references, and explicit authority limits without creating Skillpress-, Verigram-, Waylane-, or Atteway-specific envelope forks.

import {
  calculateEvidenceDigest,
  validateNeutralEvidencePacket,
} from 'attepack/evidence-protocol';

const impact = {
  type: 'skillpress.guidance_impact.v1',
  schema_version: 1,
  ok: true,
  producer: { id: 'skillpress' },
  repository: { id: 'attebury/skillpress' },
  candidate: {
    base_sha: '1111111111111111111111111111111111111111',
    head_sha: '2222222222222222222222222222222222222222',
  },
  capability_contracts: [{
    capability_id: 'skillpress.capability_contracts',
    digest: 'sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
  }],
  source_artifacts: [{
    artifact_id: 'skillpress-repo-skill',
    digest: 'sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
  }],
  authority: {
    role: 'advisory',
    owns: ['guidance_impact'],
    not_authority_for: ['merge', 'release', 'closeout', 'software_correctness'],
  },
  limitations: [{ code: 'semantic_review_not_included' }],
  evidence_refs: ['evidence/skillpress-impact.json'],
};

impact.evidence_digest = calculateEvidenceDigest(impact);
validateNeutralEvidencePacket(impact, { bindingProfile: 'candidate' });

Use bindingProfile: 'candidate' for pre-merge candidate evidence, bindingProfile: 'semantic_review' for candidate-bound review receipts that chain to parent evidence, and bindingProfile: 'merged_source' for merged-commit receipts with configured/attempted/verified target-set summaries. The digest is deterministic canonical JSON with sorted object keys and bounded arrays, strings, objects, and depth.

Security dependency pins

Install with npm ci, then assert the installed tree matches the lockfile for security-sensitive packages such as atteguard and attepack:

import { assertInstalledSecurityPins } from 'attepack/dependency-pins';

assertInstalledSecurityPins({
  packageRoot: process.cwd(),
  packages: ['atteguard', 'attepack'],
});

Use this in CI gates and doctor checks so a stale or nested duplicate install cannot pass while the lockfile documents a different version.

Fail-closed CLI JSON emit

console.log(JSON.stringify(packet)); process.exit(0) can race the async flush of process.stdout when stdout is a pipe, letting a CLI exit 0 while emitting truncated, unparseable JSON. emitJsonPacket closes that race: it only resolves (and only ever calls an injected exit hook) after the stream's write callback confirms the data was flushed.

import { emitJsonPacket } from 'attepack/cli-emit';

await emitJsonPacket(
  { type: 'wayline.verify.v1', ok: true, validity: 'authoritative' },
  { exitCode: 0 },
);
// process.exitCode is now set to 0; Node exits naturally once the packet
// is confirmed flushed, so exit status is only ever reported after the
// write completes.

Pass maxBytes to fail closed on oversized packets instead of emitting a partial payload; this throws synchronously with a typed error before any write is attempted:

import { emitJsonPacket, CLI_EMIT_ERROR_CODES } from 'attepack/cli-emit';

try {
  await emitJsonPacket(packet, { maxBytes: 1_000_000 });
} catch (error) {
  if (error.code === CLI_EMIT_ERROR_CODES.PACKET_TOO_LARGE) {
    // error.details.byteLength / error.details.maxBytes
  }
}

By default emitJsonPacket never forces process.exit; it sets process.exitCode after the flush is confirmed and lets Node exit naturally, which is sufficient to guarantee ordering. Callers that need a hard exit (e.g. to sidestep lingering handles) can opt in with an exit hook, which is still only invoked after the flush callback fires:

await emitJsonPacket(packet, { exitCode: 1, exit: process.exit });

Note that exit status alone is not proof that stdout was not truncated by something downstream of this helper (e.g. a consumer closing the pipe early); emitJsonPacket only guarantees ordering between the write and the exit signal it controls.