solana-agent-auth

Signed HTTP requests with Solana. The Solana equivalent of ERC-8128.

Every HTTP request carries a cryptographic proof that it came from a specific Solana keypair. The server verifies the proof without needing sessions, tokens, or shared secrets.

Built on RFC 9421 (HTTP Message Signatures) with native Ed25519 support.

Install

npm install solana-agent-auth

Quick Start

Client (sign requests)

import { createSignerClient } from 'solana-agent-auth'

const signer = {
  publicKey: wallet.publicKey,  // Solana Address (base58)
  signMessage: (msg) => wallet.signMessage(msg),  // returns 64-byte Uint8Array
}

const client = createSignerClient(signer)

// Sign and send in one call
const response = await client.fetch('https://api.example.com/orders', {
  method: 'POST',
  body: JSON.stringify({ side: 'buy', amount: 1.5 }),
})

// Or sign without sending
const signedRequest = await client.signRequest('https://api.example.com/data')

Server (verify requests)

import { createVerifierClient } from 'solana-agent-auth'

const verifier = createVerifierClient({ nonceStore })

const result = await verifier.verifyRequest({ request })

if (result.ok) {
  console.log(`Authenticated: ${result.publicKey}`)
  console.log(`Binding: ${result.binding}`)       // "request-bound" | "class-bound"
  console.log(`Replayable: ${result.replayable}`)  // false (nonce present) | true
} else {
  console.log(`Rejected: ${result.reason}`)        // e.g. "expired", "replay", "bad_signature_check"
}

Verification is pure Ed25519 math -- no RPC calls, no on-chain lookups, no network requests. The built-in verifier is used automatically. No external crypto library needed.

Why

Traditional HTTP authentication is credential-based. JWTs, API keys, and session cookies can all be reused if compromised, require issuance handshakes, and don't bind to specific requests. For AI agents and programmatic clients, this is especially painful -- an agent needs to authenticate to an API it has never interacted with before, prove it controls a specific wallet, and do this without a human in the loop.

solana-agent-auth replaces bearer credentials with per-request Ed25519 signatures. The client signs each HTTP request with its Solana key. The server verifies the signature. No registration, no shared secrets -- if you have a Solana keypair, you can authenticate.

How It Works

What Gets Signed

The signature covers a canonical representation of the HTTP request following RFC 9421:

"@authority": api.example.com
"@method": POST
"@path": /orders
"@query": ?market=SOL-USD
"content-digest": sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
"@signature-params": ("@authority" "@method" "@path" "@query" \
  "content-digest");created=1772587263;expires=1772587323;\
  nonce="cedf9c3d7a664e0b";keyid="solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"

This UTF-8 byte string is signed directly with Ed25519. No wrapper, no envelope -- exactly what RFC 9421 specifies.

The Headers

A signed request carries additional headers:

Header	Purpose
Signature-Input	Declares what was signed and the metadata (timestamps, nonce, signer identity)
Signature	The 64-byte Ed25519 signature, base64-encoded
Content-Digest	SHA-256 hash of the request body (auto-computed when body is present)

KeyId Format

The keyid parameter identifies who signed the request:

solana:<base58-encoded-public-key>

Example: solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU

Security Model

Two orthogonal axes controlled by the signer, evaluated by the verifier:

Request Binding

Mode	What's Signed	Use Case
Request-bound (default)	@authority + @method + @path + @query + content-digest	Authorizes exactly one HTTP request
Class-bound	Only specified components (minimum: @authority)	Authorizes a class of requests (like a scoped token)

Replay Protection

Mode	Mechanism	Use Case
Non-replayable (default)	Nonce included, server tracks consumed nonces	Single-use authorization
Replayable	No nonce, time-window only	Idempotent reads, high-frequency polling

The strongest posture (request-bound + non-replayable) is the default and is the baseline that every compliant verifier MUST accept.

Conformance

Following the ERC-8128 spec:

• Baseline (MUST accept): Request-Bound + Non-Replayable signatures
• Optional (MAY accept): Replayable or Class-Bound signatures
• Verifiers that accept Replayable signatures MUST implement early invalidation mechanisms (replayableNotBefore and/or replayableInvalidated)
• All signatures MUST include keyid, created, expires, and cover at least @authority

API

Signing

signRequest(input, signer, opts?)

Sign a request and return a new Request with Signature-Input, Signature, and Content-Digest headers.

import { signRequest } from 'solana-agent-auth'

const signed = await signRequest('https://api.example.com/data', signer, {
  label: 'sol',           // default
  binding: 'request-bound', // default
  replay: 'non-replayable', // default
  ttlSeconds: 60,           // default
})

// Also supports (input, init, signer, opts) overload:
const signed = await signRequest(
  'https://api.example.com/tx',
  { method: 'POST', body: '{"amount":100}' },
  signer
)

signedFetch(input, signer, opts?)

Sign and send a request in one call.

import { signedFetch } from 'solana-agent-auth'

const response = await signedFetch('https://api.example.com/data', signer, {
  fetch: customFetchImpl,  // optional, defaults to globalThis.fetch
})

createSignerClient(signer, defaults?)

Create a client with a bound signer and default options.

import { createSignerClient } from 'solana-agent-auth'

const client = createSignerClient(signer, {
  ttlSeconds: 120,
  fetch: customFetch,
})

// client.signRequest(input, opts?) -> Promise<Request>
// client.signedFetch(input, opts?) -> Promise<Response>
// client.fetch(input, opts?)       -> Promise<Response> (alias for signedFetch)

// All support (input, init, opts?) overload for RequestInit:
await client.fetch('https://api.example.com/tx', { method: 'POST', body: '...' })

Verification

verifyRequest(args)

Verify a signed request. Uses the built-in Ed25519 verifier by default.

import { verifyRequest } from 'solana-agent-auth'

const result = await verifyRequest({
  request,
  nonceStore,
  // verifyMessage is optional -- defaults to built-in Ed25519 verifier
  policy: {
    clockSkewSec: 5,
    maxValiditySec: 300,
  },
})

if (result.ok) {
  result.publicKey   // Address (base58)
  result.label       // "sol"
  result.components  // ["@authority", "@method", "@path", ...]
  result.params      // { created, expires, keyid, nonce? }
  result.replayable  // boolean
  result.binding     // "request-bound" | "class-bound"
}

createVerifierClient(args)

Create a verifier with bound defaults. Minimal setup -- only a NonceStore is required.

import { createVerifierClient } from 'solana-agent-auth'

const verifier = createVerifierClient({
  nonceStore,
  // verifyMessage is optional -- built-in Ed25519 verifier used by default
  defaults: {
    clockSkewSec: 5,
    maxValiditySec: 300,
  },
})

const result = await verifier.verifyRequest({ request })

Types

interface SolanaHttpSigner {
  publicKey: Address           // @solana/kit Address type (base58 string)
  signMessage: (message: Uint8Array) => Promise<Uint8Array>  // 64-byte Ed25519 sig
}

interface NonceStore {
  consume(key: string, ttlSeconds: number): Promise<boolean>
  // Returns true if newly stored (nonce not seen before)
  // Returns false if already consumed (replay attempt)
}

type VerifyResult =
  | { ok: true; publicKey: Address; label: string; components: string[];
      params: SignatureParams; replayable: boolean; binding: BindingMode }
  | { ok: false; reason: VerifyFailReason; detail?: string }

Sign Options

type SignOptions = {
  label?: string              // default: "sol"
  binding?: BindingMode       // "request-bound" | "class-bound"
  replay?: ReplayMode         // "non-replayable" | "replayable"
  created?: number            // unix seconds; default: now
  expires?: number            // unix seconds; default: created + ttlSeconds
  ttlSeconds?: number         // default: 60
  nonce?: string | (() => Promise<string>)
  contentDigest?: ContentDigestMode  // "auto" | "recompute" | "require" | "off"
  components?: string[]       // extra components to sign
}

Verify Policy

type VerifyPolicy = {
  label?: string                     // preferred label; default: "sol"
  strictLabel?: boolean              // reject if label not found; default: false
  additionalRequestBoundComponents?: string[]
  classBoundPolicies?: string[] | string[][]
  replayable?: boolean               // accept replayable sigs; default: false
  replayableNotBefore?: (keyid: string) => number | null | Promise<number | null>
  replayableInvalidated?: (args: { keyid, created, expires, label, signature, signatureBase, signatureParamsValue }) => boolean | Promise<boolean>
  maxSignatureVerifications?: number  // default: 3
  now?: () => number                 // unix seconds
  clockSkewSec?: number              // default: 0
  maxValiditySec?: number            // default: 300
  maxNonceWindowSec?: number
  nonceKey?: (keyid: string, nonce: string) => string  // default: `${keyid}:${nonce}`
}

Verify Failure Reasons

Reason	Meaning
missing_headers	Signature-Input or Signature header not present
label_not_found	No signature with the expected label
bad_signature_input	Failed to parse Signature-Input header
bad_signature	Signature did not verify
bad_signature_bytes	Could not decode signature from base64
bad_signature_check	Cryptographic verification threw or returned false
bad_keyid	keyid is not a valid solana:<address>
bad_time	created/expires are not valid integers or expires <= created
not_yet_valid	Current time is before created
expired	Current time is after expires
validity_too_long	expires - created exceeds maxValiditySec
nonce_required	Nonce present but nonceStore missing
nonce_window_too_long	expires - created exceeds maxNonceWindowSec
replay	Nonce already consumed
replayable_not_allowed	Replayable sig but policy.replayable is false
replayable_invalidation_required	Replayable sig but no invalidation mechanism configured
replayable_not_before	created is before the replayableNotBefore cutoff
replayable_invalidated	replayableInvalidated returned true
not_request_bound	Signature doesn't cover required request-bound components
class_bound_not_allowed	Class-bound sig but no classBoundPolicies configured
digest_required	content-digest in components but header missing
digest_mismatch	Content-Digest header doesn't match recomputed body hash

NonceStore Implementation

The NonceStore interface has one method. Here's a Redis example:

import { createClient } from 'redis'

const redis = createClient()

const nonceStore: NonceStore = {
  async consume(key: string, ttlSeconds: number): Promise<boolean> {
    // SET NX with TTL -- atomic check-and-insert
    const result = await redis.set(`nonce:${key}`, '1', { EX: ttlSeconds, NX: true })
    return result === 'OK'
  },
}

In-memory (for development/testing):

const nonceStore: NonceStore = {
  seen: new Map<string, number>(),
  async consume(key: string, ttlSeconds: number): Promise<boolean> {
    const now = Date.now()
    // Clean expired entries
    for (const [k, exp] of this.seen) {
      if (exp < now) this.seen.delete(k)
    }
    if (this.seen.has(key)) return false
    this.seen.set(key, now + ttlSeconds * 1000)
    return true
  },
}

Comparison with ERC-8128

This library is a direct port of @slicekit/erc8128, adapted for Solana's Ed25519 identity model.

Concern	ERC-8128 (Ethereum)	solana-agent-auth (Solana)
Algorithm	secp256k1	Ed25519
Message wrapping	ERC-191 envelope required	Raw signing (RFC 9421 native)
Account types	EOA + Smart Contract (two verification paths)	All Ed25519 (single code path)
Verification	ecrecover or ERC-1271 RPC call	Pure Ed25519 verify -- no network needed
verifyMessage	Required (bring your own viem + RPC)	Optional (ships built-in verifier)
Key to address	keccak256(publicKey)[12:] (lossy)	Public key is the address
keyid format	eip8128:<chainId>:<0xAddress>	solana:<base58Pubkey>
Default label	eth	sol
Signature return type	Hex (0x...)	Uint8Array (64 bytes)
Deterministic	No (ECDSA k-value)	Yes (Ed25519)
Signature size	65 bytes	64 bytes
Success result	{ address, chainId }	{ publicKey }

Spec Compliance

The implementation is 34/35 compliant with the ERC-8128 specification, with Ethereum-specific parts (ERC-191, secp256k1, chain-id, ERC-1271) replaced by Solana equivalents (raw Ed25519, base58 addresses). The single partial compliance (§5.2: invalidation requests must be authenticated with request-bound signatures) is an application-layer concern outside the scope of a signing library.

Architecture

src/
├── sign.ts                    # signRequest(), signedFetch()
├── verify.ts                  # verifyRequest()
├── client.ts                  # createSignerClient()
├── verifierClient.ts          # createVerifierClient()
├── index.ts                   # barrel exports
└── lib/
    ├── types.ts               # all types + SolanaAuthError
    ├── keyId.ts               # formatKeyId(), parseKeyId()
    ├── nonce.ts               # resolveNonce()
    ├── utilities.ts           # base64, sha256, toRequest, etc.
    ├── defaultVerify.ts       # built-in Ed25519 verifier
    ├── verifyUtils.ts         # buildAttempts, time/nonce checks
    ├── acceptSignature.ts     # Accept-Signature response header
    ├── engine/
    │   ├── serializations.ts       # RFC 8941 structured field serialization
    │   ├── createSignatureBase.ts  # RFC 9421 signature base construction
    │   ├── createSignatureInput.ts # Signature-Input / Signature parsing
    │   ├── contentDigest.ts        # Content-Digest (RFC 9530)
    │   └── signatureHeaders.ts     # signature candidate selection
    └── policies/
        ├── isRequestBound.ts       # request-bound classification
        └── normalizePolicies.ts    # policy normalization

Standards

• RFC 9421 -- HTTP Message Signatures
• RFC 9530 -- Digest Fields (Content-Digest)
• RFC 8941 -- Structured Field Values
• ERC-8128 -- Signed HTTP Requests with Ethereum (the Ethereum equivalent)

Development

bun install
bun test       # 225 tests
bun run build

License

MIT