DevPortal: Developer Portal SDK

Executive Summary

DevPortal provides the core building blocks for developer portals: API key lifecycle management with cryptographically secure secret generation, usage analytics with daily bucketing, and trust registry exploration with filtering and pagination.

Three function groups cover the entire surface area: API Key Management generates keys with SHA-256 hashed secrets, validates incoming requests, and supports revocation. Usage Analytics records request metadata (endpoint, latency, status code) and computes aggregate statistics by day, endpoint, and error rate. Registry Explorer searches trust registry entries with name/scope filters and paginated results.

Every API key secret is generated with crypto.getRandomValues() (32 bytes / 256 bits) and immediately SHA-256 hashed. The plaintext secret is returned exactly once and never stored. Validation uses constant-time hash comparison. Scope checking is built in.

Zero npm dependencies. Runs on any platform with Web Crypto API: Node.js 20+, Tauri v2, modern browsers, Deno, Bun. Dual ESM/CJS builds in a single package.

Developer Experience

Six structured error codes with actionable hints. Immutable type contracts prevent accidental mutation. Result-based error handling with no thrown exceptions.

interface PortalError {
  code: PortalErrorCode;    // INVALID_KEY | KEY_EXPIRED | KEY_REVOKED | NOT_FOUND | RATE_LIMITED | UNAUTHORIZED
  message: string;           // Human-readable description
}

Immutable Types

All fields are readonly. TypeScript enforces immutability at compile time. Accidental mutation is a type error.

interface ApiKey {
  readonly keyId: string;
  readonly hashedSecret: string;
  readonly label: string;
  readonly scopes: readonly string[];
  readonly createdAt: number;
  readonly expiresAt: number | null;
  readonly revokedAt: number | null;
}

The Problem

Developer portals need API key management, but building it from scratch means reinventing cryptographic randomness, hash verification, scope authorization, usage tracking, and registry search. Most teams get at least one of these wrong.

Weak secret generation. Many implementations use Math.random() or insufficiently long secrets. DevPortal uses crypto.getRandomValues() with 32 bytes (256 bits) of entropy.

Plaintext secret storage. Storing API secrets in plaintext or reversible encryption creates breach risk. DevPortal immediately SHA-256 hashes secrets and never persists plaintext.

No scope enforcement. API keys often grant global access instead of scoped permissions. DevPortal includes scope-based authorization with constant-time checking.

No usage visibility. Without analytics, developers can't debug rate limits or optimize request patterns. DevPortal tracks every request with latency, status code, and endpoint bucketing.

Real-World Use Cases

Six scenarios where DevPortal replaces custom API key infrastructure with a zero-dependency SDK.

Solution Architecture

Three composable modules. Each module is independent but designed to work together.

Integration

Five functions cover 90% of developer portal needs. Start with key generation, add analytics when needed, integrate registry search for multi-tenant portals.

import {
  generateApiKey,
  validateApiKey,
  recordUsage,
  computeStats,
} from '@private.me/devportal';

// In-memory key store (use persistent storage in production)
const keys = new Map();
const usageRecords: UsageRecord[] = [];

// Generate key
const result = await generateApiKey({
  label: 'Production',
  scopes: ['gateway:deliver', 'registry:read'],
  expiresInDays: 90,
});

if (!result.ok) throw new Error(result.error.message);

const { key, secret } = result.value;
keys.set(key.keyId, key);
console.log('API Key:', key.keyId);
console.log('Secret (save this, shown once):', secret);

// Validate incoming request
const valid = await validateApiKey(receivedKeyId, receivedSecret, keys);
if (!valid.ok) {
  return { status: 401, error: valid.error };
}

// Record usage
recordUsage({
  keyId: key.keyId,
  endpoint: '/gateway/deliver',
  timestamp: Date.now(),
  responseMs: 42,
  statusCode: 200,
}, usageRecords);

// Compute stats
const stats = computeStats(usageRecords, { keyId: key.keyId });
console.log('Total requests:', stats.totalRequests);
console.log('Avg latency:', stats.avgResponseMs);
console.log('Error rate:', stats.errorRate);

Persistent Storage

DevPortal uses in-memory Map and arrays for simplicity. Production deployments need persistent storage. The caller is responsible for serializing API keys and usage records to a database or file system.

// Load keys from database on startup
const keys = new Map();
const rows = await db.query('SELECT * FROM api_keys');
for (const row of rows) {
  keys.set(row.keyId, row);
}

// After generating a new key, persist to DB
const result = await generateApiKey({ label, scopes, expiresInDays });
if (result.ok) {
  await db.insert('api_keys', result.value.key);
  keys.set(result.value.key.keyId, result.value.key);
}

Registry Integration

The registry explorer operates on an array of RegistrySearchResult entries. In production, these typically come from a trust registry (Xlink) or identity provider.

import { searchRegistry, getRegistryStats } from '@private.me/devportal';

// Fetch entries from trust registry
const entries = await trustRegistry.listAll();

// Search by name, scope, pagination
const results = searchRegistry(entries, {
  query: 'production',          // Case-insensitive name search
  scope: 'gateway:deliver',    // Filter to entries with this scope
  includeRevoked: false,         // Exclude revoked entries
  limit: 20,                    // Max results per page
  offset: 0,                   // Pagination offset
});

// Get aggregate stats
const stats = getRegistryStats(entries);
console.log('Total entries:', stats.total);
console.log('Active entries:', stats.active);
console.log('By scope:', stats.byScope);

Security

Four cryptographic guarantees: random secret generation, irreversible hashing, constant-time comparison, and scope-based authorization.

Hash Verification Flow

Validation checks occur in sequence: (1) key existence, (2) revocation status, (3) expiry, (4) SHA-256 hash comparison. If any check fails, validation returns an error immediately without proceeding to the next step.

Benchmarks

Performance measurements on Node.js 20.x, Apple M2 Pro. All operations are sub-millisecond except SHA-256 hashing (~50µs).

Honest Limitations

DevPortal is designed for simplicity and zero dependencies. Some features are intentionally deferred to the application layer.

In-Memory Storage Only

API keys and usage records are stored in Map and arrays. The caller is responsible for persistence to a database or file system. DevPortal provides the building blocks, not a complete storage solution.

No Rate Limiting Implementation

The RATE_LIMITED error code exists in the type system, but DevPortal does not implement rate limiting. Use @private.me/xgate or a similar rate limiter at the transport layer.

Linear Scope Checking

hasScope() uses Array.includes(), which is O(n) where n is the number of scopes. For keys with 100+ scopes, consider converting to a Set at the application layer.

No Scope Hierarchies

Scopes are literal strings. There is no support for wildcard scopes (e.g., admin:*) or hierarchical scopes (e.g., read implies read:all). Implement scope expansion logic before calling hasScope().

Stats Recomputation on Every Call

computeStats() iterates through all usage records on every call. For large datasets, cache the result at the application layer and invalidate on new records.

No Automatic Key Rotation

DevPortal provides expiry support but does not automatically generate replacement keys. The developer portal must implement rotation workflows (e.g., email notifications before expiry, automatic generation of new keys).

Full API Surface

Complete function reference with signatures and descriptions.

API Key Management

Usage Analytics

Registry Explorer

Type Reference

Complete type definitions with field descriptions.

interface ApiKey {
  readonly keyId: string;              // UUID v4 via crypto.randomUUID()
  readonly hashedSecret: string;       // SHA-256 hash (hex-encoded)
  readonly label: string;              // Human-readable label
  readonly scopes: readonly string[]; // Permission scopes
  readonly createdAt: number;          // Unix epoch ms
  readonly expiresAt: number | null;  // Unix epoch ms or null (non-expiring)
  readonly revokedAt: number | null;  // Unix epoch ms or null (active)
}

interface UsageRecord {
  readonly keyId: string;       // API key ID
  readonly endpoint: string;    // API endpoint path (e.g., /gateway/deliver)
  readonly timestamp: number;   // Unix epoch ms
  readonly responseMs: number;  // Response latency in milliseconds
  readonly statusCode: number;  // HTTP status code
}

interface UsageStats {
  readonly totalRequests: number;              // Total request count
  readonly avgResponseMs: number;              // Average latency
  readonly errorRate: number;                  // Fraction of status >= 400 (0.0 to 1.0)
  readonly requestsByEndpoint: Record<string, number>;  // Count by endpoint
  readonly requestsByDay: Record<string, number>;       // Count by ISO date (YYYY-MM-DD)
}

interface RegistrySearchResult {
  readonly did: string;                // Decentralized Identifier
  readonly name: string;               // Display name
  readonly scopes: readonly string[];  // Permission scopes
  readonly createdAt: number;          // Unix epoch ms
  readonly revoked: boolean;           // Revocation status
}

Error Code Taxonomy

Complete error code reference with causes and actions.

Related Packages

DevPortal composes with other PRIVATE.ME packages to build complete developer portal infrastructure.