@axtary/config

YAML configuration loading for local Axtary runtime packages.

Early 0.x release: the runtime path is real and tested, but the API is not stable yet and may change between minor versions.

The source repository is currently private. Public product documentation and runnable guides are at axtary.com/docs.

npm install @axtary/config

What It Does

• Parses axtary.yml text into a typed runtime config.
• Applies defaults for issuer, tenant, ledger path, runtime mode, adapters, and policy.
• Normalizes policy through @axtary/policy.
• Resolves ledger paths relative to the config file or current working directory.
• Emits a default config template for demos.
• Provides CachedConfigLoader for long-running local proxy sessions.

Adapter Config

GitHub defaults to credential-free demo mode (the v0 config literal is fake):

adapters:
  github:
    mode: fake

To route allowed GitHub actions to the real REST API, set:

adapters:
  github:
    mode: rest
    tokenEnv: GITHUB_TOKEN
    apiBaseUrl: https://api.github.com
    userAgent: axtary-local-proxy

Slack and Linear follow the same credential-free demo-first pattern:

adapters:
  slack:
    mode: web
    tokenEnv: SLACK_BOT_TOKEN
    apiBaseUrl: https://slack.com/api
  linear:
    mode: graphql
    tokenEnv: LINEAR_API_KEY
    apiUrl: https://api.linear.app/graphql

Linear and Jira schemas/defaults are consumed from the same native-connector governance descriptors that drive evidence and doctor metadata, so a connector cannot silently drift between config and operator guidance.

Jira Cloud supports API-token and OAuth-backed REST modes:

adapters:
  jira:
    mode: rest
    auth: api_token
    emailEnv: JIRA_EMAIL
    tokenEnv: JIRA_API_TOKEN
    siteUrl: https://your-site.atlassian.net

For OAuth, set auth: oauth; axtary connect jira stores the access/refresh tokens and discovered cloud ID in the local credential broker.

Google Drive uses one-file Picker OAuth and a separate policy allowlist:

adapters:
  drive:
    mode: rest
    maxReadBytes: 100000
policy:
  drive:
    reads:
      allowedFileIds: [YOUR_PICKED_FILE_ID]
      maxReadBytes: 100000

Run axtary connect drive --redirect-uri https://<tunnel>/callback; the drive.file token and selected file id stay in the local credential broker.

The CLI reads tokens from the named environment variables. Keep credential-free demo mode for demos and tests; switch to the implemented live mode when you want provider calls.

Local docs are enabled by default and resolve roots relative to the config file:

adapters:
  docs:
    mode: local
    workspace: local
    roots:
      - docs
      - product
    maxSearchResults: 10
    maxReadBytes: 20000

Pair this with policy.docs.documents to scope allowed workspaces, readable path prefixes, denied prefixes, and per-action limits.

Multi-rule policy block

The legacy policy: section remains the built-in preset's configuration. Define policies: to activate the named rule engine:

policies:
  defaultDecision: deny
  rules:
    - id: allow-local-docs
      match:
        tools: docs.documents.*
        resources: docs:*
      effect: allow
      obligations:
        expiresInSeconds: 120
        blockedPathPrefixes: [private/, secrets/]

See examples/axtary.policies.yml for a complete multi-rule configuration.

Runtime Latency Guard

runtime:
  handlerTimeoutMs: 10000

Handlers that exceed the timeout fail closed with proxy_handler_timeout:<ms>ms. Proxy responses include per-stage timings so local runs can track policy, signing, ledger, and adapter latency.

Runtime budgets

Budget enforcement is disabled by default. Limits and costs are authority-owned configuration:

runtime:
  budget:
    enabled: true
    scope: tenant # tenant | actor | task
    limits:
      actions: 100
      externalMessages: 10
    costs:
      "*":
        actions: 1
      slack.chat.postMessage:
        externalMessages: 1

Wildcard and exact-tool costs are additive. An enabled budget requires the "*" cost and every cost dimension must have a limit; incomplete trusted configuration fails at runtime startup. This is local metering for enforcement and ledger evidence, not pricing or billing configuration.

ActionPass status distribution

ActionPass v2 status distribution is enabled by default:

runtime:
  status:
    enabled: true
    keyringPath: .axtary/keys/actionpass-issuer-keyring.json
    storePath: .axtary/actionpass-status.json
    ttlSeconds: 60
    expiresInSeconds: 120

The keyring and status store are private local authority state. The proxy publishes public JWKS and a signed freshness-bounded status list; verifiers fail closed when required status is unavailable, stale, or invalid.

Generic SSF/CAEP ingestion is opt-in:

runtime:
  caep:
    enabled: true
    issuer: https://transmitter.example
    audience: https://local.axtary.dev/ssf/events
    jwksUri: https://transmitter.example/.well-known/jwks.json
    mappingPath: .axtary/caep-mappings.json
    replayPath: .axtary/ssf-replay.json

When enabled, issuer, audience, and JWKS URI are required at startup. An optional bearerTokenEnv adds a shared transport credential without placing its value in config. Signed CAEP subjects still require explicit caep-map root-pass mappings; Axtary does not infer identity-provider associations.

Cached Loading And Hot Reload

CachedConfigLoader caches parsed configs and checks the config file mtime on getConfig(). File-backed configs reload automatically when axtary.yml changes, which lets the local proxy pick up policy edits without a restart.

Deterministic provenance enforcement is opt-in under the policy block:

policy:
  provenance:
    enabled: true
    unknownDecision: deny
    untrustedDecision: step_up

Enabling it without a trusted runtime provenance resolver intentionally causes covered egress fields to fail closed as provenance_unknown_egress.

If a file-backed config disappears or becomes unreadable, the loader throws instead of silently serving stale policy. The proxy records that as a fail-closed policy-resolution denial.

Quickstart

This example runs as-is with Node 20+:

import { parseAxtaryConfigYaml, DEFAULT_AXTARY_CONFIG_YAML } from "@axtary/config";

// Parse and validate an axtary.yml (here: the scaffold `axtary init` writes).
const config = parseAxtaryConfigYaml(DEFAULT_AXTARY_CONFIG_YAML);
console.log(config.policy ? "policy loaded" : "no policy", Object.keys(config));

Design Notes

Config parsing is intentionally separate from the CLI so adapters, tests, and future MCP wrappers can all share the same file format.