SDK Authentication

The rickydata SDK provides an AuthManager class with multiple authentication strategies for different environments.

Installation

npm install @nickydata/sdk

AuthManager

The AuthManager class manages authentication state, token refresh, and re-authentication automatically.

import { AuthManager } from '@nickydata/sdk';

const auth = new AuthManager('https://api.knowledgedataflow.org');

Authentication Strategies

authenticateAuto() — Recommended for Production

The safest strategy for production. It automatically selects the best authentication method based on available credentials:

1. ERC-8128 signer (if signer + operator wallet match)
2. Wallet token (self-verifying mcpwt_ token that survives restarts)
3. Challenge/verify fallback (EIP-191 signature flow)

const session = await auth.authenticateAuto({
  signFn: wallet.signMessage,
  walletAddress: wallet.address,
});

// Token auto-refreshes on expiry
const response = await auth.fetchWithAuth(
  'https://api.knowledgedataflow.org/api/v1/query',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: 'MATCH (n) RETURN count(n)' }),
  }
);

authenticateWithWalletToken()

Creates a long-lived, self-verifying token (mcpwt_...) that survives gateway restarts. Best for persistent connections.

const session = await auth.authenticateWithWalletToken(
  wallet.signMessage,       // EIP-191 sign function
  wallet.address,           // Wallet address
  '2027-01-01T00:00:00Z',  // Token expiry (ISO 8601)
);
// session.token starts with "mcpwt_"

The wallet token flow:

1. SDK requests a canonical message from the gateway
2. User signs the message with their wallet
3. Gateway creates a self-verifying token from the signature

authenticateWithSignature()

Standard EIP-191 challenge/verify flow. Returns a JWT valid for 24 hours.

const session = await auth.authenticate(
  wallet.signMessage,  // EIP-191 sign function
  wallet.address,      // Wallet address
);
// session.token is a JWT

authenticateWithGitHubOIDC() — For CI/CD

Authenticate using GitHub Actions OIDC tokens. No wallet or private key needed — the GitHub runner proves its identity to the gateway.

Requires permissions: id-token: write in your workflow.

const session = await auth.authenticateWithGitHubOIDC(
  'owner/repo',  // GitHub repository
);

# .github/workflows/example.yml
jobs:
  query:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - run: npm install @nickydata/sdk
      - run: node scripts/query-kfdb.js

Making Authenticated Requests

Use fetchWithAuth() for automatic token management:

// Automatically adds Bearer header and refreshes expired tokens
const response = await auth.fetchWithAuth(
  'https://api.knowledgedataflow.org/api/v1/query',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: 'MATCH (n:File) RETURN n.path LIMIT 5' }),
  }
);

const data = await response.json();

Token Lifecycle

Property	Description
auth.isAuthenticated	Whether a valid token exists
auth.isExpired	Whether the token has expired (with 60s safety margin)
auth.canReauthenticate	Whether stored credentials allow automatic re-auth
auth.getToken()	Get the current token string
auth.getAuthHeaders()	Get headers object with Authorization: Bearer ...

Re-authentication happens automatically in fetchWithAuth() when a token expires. Concurrent re-auth calls are deduplicated.