@axtary/adapters

Tool adapters for deterministic evaluation and explicitly configured real-provider execution through Axtary.

Early 0.x release: the runtime path is real and tested, but the API is not stable yet and may change between minor versions. Deterministic credential-free demo adapters remain the safe default, and implemented GitHub, Slack, Linear, Jira Cloud, Postgres read, Google Drive read, AWS, GCP, and local docs handlers are available behind explicit config.

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

npm install @axtary/adapters

What It Does

• Provides deterministic GitHub PR and content-read demo handlers.
• Provides a deterministic Slack message demo handler.
• Provides deterministic Linear and Jira issue/comment/update demo handlers.
• Wraps handlers with ActionPass verification so adapter-side effects require a valid payload-bound pass.
• Resolves issuer verification keys by kid and, for ActionPass v2, requires the host's authenticated status checker before adapter credentials are used.
• Provides real GitHub REST handlers for content reads, branch creation, content writes, PR creation, inline review comments, check-runs, and issue comments.
• Provides a real Slack Web API handler for chat.postMessage.
• Provides real Linear GraphQL handlers for issue reads, comments, and updates.
• Provides a descriptor-driven native-connector harness. GitHub, Jira, Linear, Postgres, and Google Drive now derive capability metadata, evidence dispatch, config defaults, required scopes, smoke identity, and doctor plans from the same governance contract used by their runtime handlers.
• Keeps environment access explicit: connector readiness reporting requires the caller to pass the env map it should assess (presence checks only, never values) and fails closed without one, so the package does not read ambient process.env on its own.
• Keeps provider network access explicit: GitHub App/REST, Slack, Linear, Jira, Drive, AWS, and GCP clients require the host to inject a fetch-compatible transport and fail closed with provider-specific *_fetch_required reasons. The library never falls back to ambient global network access.
• Provides a real Jira Cloud REST v3 implementation for issue reads, ADF comments, field updates, and workflow transitions.
• Provides a narrow Postgres SELECT adapter with parsed statement/table/predicate checks, parameter binding, bounded rows/timeouts, read-only transactions, least-privilege role checks, and RLS verification.
• Provides a narrow Google Drive drive.file adapter that reads one Picker-authorized, policy-allowlisted file, requires provider isAppAuthorized, and keeps tokens/content out of ledger evidence.
• Provides read-only AWS REST handlers for STS identity and S3 object listing.
• Provides read-only GCP REST handlers for project reads and Cloud Storage object listing.
• Provides local docs search/read handlers with configured roots, result/byte caps, path traversal protection, and redaction.
• Provides non-destructive smoke helpers for GitHub /user, Slack auth.test, Linear viewer, Jira /myself, Postgres role/RLS metadata, Google Drive selected-file metadata, AWS STS GetCallerIdentity, GCP project access, and local docs roots.
• Classifies provider rate limits, server errors, auth errors, and provider errors for retries and diagnostics. GitHub honors Retry-After/X-RateLimit-Reset and returns accepted-permission plus rate-limit metadata as non-secret execution proof.
• Captures adapter state in memory for tests and local demos.
• Returns predictable JSON payloads from proxy handlers.

Smoke Helpers

The smoke helpers exercise the same provider clients as the real handlers, but only call read/auth endpoints:

• smokeGitHubRestCredentials
• smokeSlackWebCredentials
• smokeLinearGraphqlCredentials
• smokeJiraRestCredentials
• smokePostgresCredentials
• smokeDriveRestCredentials
• smokeAwsRestCredentials
• smokeGcpRestCredentials
• smokeLocalDocsRoots

They are used by axtary smoke to validate credentials before running a real integration.

Native connector descriptor

GITHUB_NATIVE_CONNECTOR, LINEAR_NATIVE_CONNECTOR, JIRA_NATIVE_CONNECTOR, POSTGRES_NATIVE_CONNECTOR, and DRIVE_NATIVE_CONNECTOR extend the canonical ActionPass governance descriptor with handler factories, smoke execution, and secret-safe doctor wiring. Adding a tool to either provider updates one tool entry for capability/evidence metadata plus its handler implementation; config, doctor, and dashboard capability surfaces no longer need parallel per-tool edits.

The descriptor does not grant authority. Policy evaluation and adapter-side ActionPass verification remain the execution boundary.

Quickstart

This example runs as-is with Node 20+:

import { createFakeHandlers, createLocalDocsHandlers, getConnectorCapabilities } from "@axtary/adapters";

// Demo handlers cover the full workflow without credentials or provider calls.
console.log(Object.keys(createFakeHandlers()));

// Real handlers are created the same way, behind explicit config.
const docs = createLocalDocsHandlers({
  roots: ["./docs"],
});
console.log(Object.keys(docs));

// The capability registry says which capabilities are real vs demo-only.
console.log(getConnectorCapabilities().filter((c) => c.status === "supported").length, "supported capabilities");

Design Notes

The credential-free demo adapters prove the authorization flow deterministically without provider calls. Live adapters remain wrapped with ActionPass verification so the proxy and adapter boundary both enforce the same action hash, audience, issuer, expiration, holder proof, and—when v2 is presented—fresh authenticated status.