Part 3: The User Provider Auto-Connect Layer — When Our Runtime Needs
to Talk to Your APIs
This is Part 3 of our Infrastructure Series. In Part 1, we introduced the vision. In Part 2, we covered our
internal runtime — fetch service, dynamic loader, and engine registry. That runtime is fully sovereign:
universal web search, local crawlers, offline pipelines. It never needs external APIs to function.
But sometimes you want our runtime to talk to your services — your Stripe, your Twilio, your OpenAI
account. That’s what this layer is for.
A deep dive into architecting user-owned third-party provider management with zero hardcoded defaults,
12-dimensional identity isolation, and full offline-first design.
The Problem
Our runtime is fully sovereign. Universal web search with local crawlers. Internal data pipelines that
never touch the cloud. The fetch service, dynamic loader, and engine registry from Part 2? They work
in an air-gapped room with zero external dependencies.
But sometimes a user says: “I want to send an SMS through my Twilio account.” Or: “Process this
payment through my Stripe.” Or: “Run this inference on my OpenAI key.” They want us to orchestrate
their infrastructure — without us ever seeing their credentials. That’s a different problem from keeping
our own runtime running — AI APIs, payment processors, communication platforms, cloud infrastructure.
And we kept seeing the same two traps in every codebase we audited:
The vendor SDK trap: You import stripe, twilio, openai directly. Your codebase becomes a
dependency hairball. Updates break everything. Secrets leak into environment variables with zero
rotation.The hardcoded config trap: You write a config.js with API URLs, timeout values, and provider
lists baked in. It works for 3 providers. At 50, it’s unmaintainable. At 200+, it’s a disaster.
So we built the Provider Auto-Connect Service — not for our own operations (those are already sovereign),
but for user-owned integrations. When you want to send an SMS through your Twilio, process a payment
through your Stripe, or run inference on your OpenAI account — without us ever seeing your keys: 234
providers across 24 categories, with zero hardcoded operational values, per-identity isolation, and full
offline-first design.
What It Actually Does
At its core, this service answers one question: “Given a user’s intent and their configured credentials,
which providers can we safely connect to right now?”
But the implementation goes much deeper:
Provider Registry (234 Built-In + Unlimited Custom)
Our registry ships with 234 pre-defined providers across 24 categories:
CategoryExamples
AI & MLOpenAI, Anthropic, Groq, Ollama, LM Studio,
Neurenix
CommunicationTwilio, SendGrid, Slack, WhatsApp Business
PaymentStripe, PayPal, Paystack, Flutterwave, M-Pesa
CloudAWS, GCP, Azure, Vercel, Cloudflare
DatabaseMongoDB, PostgreSQL, Redis, Supabase,
Pinecone
AuthAuth0, Clerk, Okta, Keycloak
BlockchainAlchemy, Infura, Thirdweb
⋯and 17 moreDomain, SMTP, SSL, Hosting, CRM,
E-commerce
Key insight: Our users register any custom provider we don’t know about. The registry isn’t a closed
list — it’s a starting point.
// Register a custom provider for your infrastructure//
const custom = registerCustomProvider({
name: 'MyInternalLLM',
requiredCredentials: ['MY_LLM_API_KEY'],
testEndpoint: 'http://internal-llm.company.local/health',
features: ['chat', 'embeddings'],
}, { autoConnect: true, identity: runtimeContext });
- Offline-First by Default Before any external API is touched, the service checks local providers first. Ollama, LM Studio, Neurenix, Chroma, Meilisearch, MinIO — these require no internet, no API keys, no cloud accounts. They just work.
// With INTERNET_ENABLED=false, only local providers are considered//
const localOnly = await autoConnectProviders({ userId: 'alice' },
{ filter: (p) => p.regions.includes('local') });
// localOnly.connected -> [ollama, lmstudio, chroma, meilisearch, minio]
External providers (OpenAI, Stripe, Twilio) are gated by INTERNET_ENABLED. No accidental cloud
calls. No surprise bills. Local inference, local storage, local search — all available out of the box.
- Composite Identity (12 Dimensions)
//Every operation is scoped to a 12-dimensional composite identity://
const identity = buildCompositeIdentity({
userId: 'alice',
tenantId: 'acme-corp',
orgId: 'engineering',
projectId: 'api-gateway',
sector: 'fintech',
role: 'admin',
username: 'alice.smith',
sessionId: 'sess-abc123',
keyid:'',
username: ''
});
// identity.compositeKey =
//
"alice::acme-corp::engineering::api-gateway::fintech::admin::alice.smith::sess-abc123"
// identity.hash = "a3f7b2d9e1c8a4b5" (first 16 chars of SHA-256)
Why 12 dimensions? Because “per-user” isn’t enough. Alice the admin in the fintech sector with
an enterprise license needs different provider policies than Alice the guest in the demo sandbox. The
composite key ensures zero cross-identity leakage.
- Flat Dimension-Encoded Storage (No Nesting) Storage uses dimension-encoded filenames in flat directories — no deep nesting, but still queryable by prefix:
data/
├── audit/
│
└── provider_auto_connect/
│├── pac_alice#acme-corp#engineering#api-gateway#fintech#admin#a3f7b2d9...jsonl
│├── pac_alice#acme-corp#engineering#api-gateway#fintech#admin#a3f7b2d9...jsonl.1720406400000.gz
│└── archive/
│
└── consents/
├── consents_alice#acme-corp#engineering#api-gateway#fintech#admin#a3f7...json
└── consents_bob#acme-corp#sales#crm#fintech#user#b2c0...json
The mask is configurable via STORAGE_IDENTITY_MASK:
// Default: userId, tenantId, orgId, projectId, sector, role
// Excludes: sessionId (ephemeral), keyId (rotates), username (redundant), entityType,
organizationSize, licenseType
// Query all consents for a tenant:
fs.readdirSync(consentsDir)
.filter(f => f.startsWith(`consents_#acme-corp#`))
- Zero Hardcoded Defaults Every operational value flows through a 5-source env cascade:
process.env → .env / env.json / .env.bak → config.json → orchestrator_defaults.json → fallback param
// Not this://
const TIMEOUT = 5000;
// This://
const TEST_TIMEOUT_MS = _envInt('TEST_TIMEOUT_MS', 5000);
The module exposes 40+ env vars covering timeouts, thresholds, retention policies, default endpoints, hash
lengths, separators, storage identity masks — everything. The compliance flag zeroHardcodedDefaults:
true isn’t aspirational. It’s enforced.
- Production-Safe Debug Output Every console.log in a production service is a liability. Stack traces leak. User IDs leak. Timing information leaks. We gate every debug statement behind an environment flag:
// Not this://
console.log(`Connecting to ${providerId}...`);
// This://
if (isDebugEnabled()) {
console.log(`[provider-auto-connect] ${providerId}: connection attempt`);
}
The isDebugEnabled() check reads from the same env cascade as everything else — DEBUG_ENABLED, .env,
config files, fallback to false. Default is off. In production, zero console output.
But we don’t just silence logs. We redirect them. output goes through a
structured channel with identity context:
_debug('connection_attempt', {
providerId: 'stripe',
identity: compositeKey,
timestamp: Date.now()
});
This gives us searchable, context-rich debug traces without ever accidentally printing a raw object to
stdout.
┌─────────────────────────────────────────┐
│
DEBUG OUTPUT GATE
│
│
│
│┌─────────────┐││││ DEBUG_ENABLED││ (default)
│└─────────────┘└─────────────┘
││
│
env check
┌─────────────┐
│───→│
false
│
│───→│──→ /dev/null
│
│
│
│
▼ true
│
│┌─────────────────────────────────┐│
││Structured _debug() channel│
││with identity + timestamp
│
│
│
└─────────────────────────────────┘│
│││
│▼│
│console.log (dev only)│
│
│
or
PME audit stream (prod)
│
│
└─────────────────────────────────────────┘
- Infrastructure Delegation with Inline Fallbacks The service doesn’t implement resilience patterns from scratch. It delegates to our infrastructure and falls back to inline implementations for standalone use: Delegation TargetWhat It HandlesInline Fallback fetch_serviceRobust fetch, per-user circuitNative fetch with timeout breaker, rate limiting, audit logging silent_provider_provisioner Policy engine, anomaly detection, Inline confirmation gates, if external handler is unavailable attestation, geo-routing, compression sqlite_storeAtomic SQLite persistenceAtomic JSON temp+rename pme_logger Structured audit logging Per-user provider preferencePer-identity JSONL files No-op (non-fatal) auto_pattern_learner learning dynamic_learning Per-user + system-wide No-op (non-fatal) anonymized learning
This design means the service works standalone (no infrastructure present) and enhanced (full stack
available) without code changes.
- Intent-Based Provider Routing The entry point:
const result = await routeIntentToProviders(
"Send an email to the team about the deployment",
identity,
{ autoConnect: true }
);
// result.matched -> [{ id: 'sendgrid', name: 'SendGrid', configured: true, hasConsent: true }]
// result.connected -> [{ id: 'sendgrid', message: 'SendGrid connected successfully' }]
It works through three layers:
- Keyword detection: 130+ keyword mappings (loaded from config with inline fallback + adaptive learning)
Intent engine delegation: If available, uses intent engine resolve() for semantic matching
Fuzzy scoring: Token-based scoring on name, description, and features as last resort
Critical: It never throws. If nothing matches, it returns suggestions with confidence scores.The Full Auto-Connect Loop
const results = await autoConnectProviders(identity, {
onConnect: (id, msg) => _debug(`§$\vcenter{{\hbox{{\includegraphics[height=\ht\strutbox]{{/usr/share/
docminer/emoji/2713.png}}}}}}$§ ${id}: ${msg}`),
onSkip: (id, reason) => _debug(`⊘ ${id}: ${reason}`),
onError: (id, err) => _debug(`§$\vcenter{{\hbox{{\includegraphics[height=\ht\strutbox]{{/usr/share/
docminer/emoji/2717.png}}}}}}$§ ${id}: ${err}`)
});
For every provider:
- Region check — Skip if not available in user’s region
- Config check — Skip if required env vars missing (via Key Vault → env cascade)
- Consent check — Skip if consent required but not granted
- Confirmation gate — Skip if policy engine denies (for external providers)
- Internet gate — Skip if external and INTERNET_ENABLED=false
- Circuit breaker — Skip if breaker is OPEN for this identity+provider
- Rate limit — Skip if throttled
- Connection test — Actually hit the provider’s health endpoint
- Learn — Record success/failure in pattern learner / learning engine for future ranking
- Structured Audit Logging Every connection attempt, skip, failure, and success is an audit event. Not a console line — a structured record with full identity context, timestamp, and outcome. We route these through the PME logger. The PME stream isn’t a database you query. It’s an append-only sequence of identity-scoped events:
{
"event": "provider_connected",
"timestamp": "2026-07-08T01:52:00Z",
"identity": "alice#acme-corp#engineering#api-gateway#fintech#admin#a3f7...",
"provider": "stripe",
"outcome": "success",
"latencyMs": 245,
"region": "us-east-1"
}
These events flow through the PME logger when available. When running standalone, they fall back to
per-identity JSONL files — never a shared audit table, never cross-identity leakage.
The PME serves two purposes:
- Compliance: Every provider touch is recorded, immutable, identity-bound Learning: The auto-pattern learner and dynamic learning engine read PME streams to build provider preference models
// Delegated path (full infrastructure available)
await structuredLogger.append({
event: 'provider_connection_test',
identity: compositeKey,
providerId: 'stripe',
result: 'success',
metadata: { latencyMs: 245 }
});
// Standalone fallback (no infrastructure present)
await writeIdentityJsonl(compositeKey, {
event: 'provider_connection_test',
timestamp: Date.now(),
providerId: 'stripe',
result: 'success'
});
Why JSONL and not SQLite for audit? Because audit streams are append-only and query patterns
are “read all events for this identity in this time range.” JSONL is trivial to grep, compress, and archive.
SQLite is for structured relational data — not append-only event streams.
┌─────────────────────────────────────────────────────────────┐
│
PME AUDIT STREAM
│
│
│
│
Every gate in the auto-connect loop emits:
│
│
│
│Region Check──→ event: "region_skip"│
│Config Check──→ event: "config_missing"│
│Consent Check──→ event: "consent_denied"│
│Confirm Gate──→ event: "policy_denied"│
│Internet Gate──→ event: "internet_gated"│
│Circuit Breaker ──→ event: "breaker_open"│
│Rate Limit──→ event: "rate_limited"│
│Connect Test──→ event: "connection_success"/"failure" │
│
│
│
All events → PME stream → per-identity JSONL
│
│
│
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│
AUDIT LIFECYCLE (30d / 90d)
│
│
│
│0-30d→hot JSONL in data/audit/provider_auto_connect/│
│30-90d→gzip to archive/│
│90d+→delete (or cold storage, env-driven)│
│
│
└─────────────────────────────────────────────────────────────┘
Data Lifecycle (30d / 90d)
Audit logs auto-prune:
• > 30 days: Deleted
• > 90 days: Gzipped to archive/
• Interval: Env-driven (default 24h)
All per-identity. No shared directories. No global tables.
Architecture Diagrams
Intent-to-Connection Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│
USER INTENT / COMMAND
│
│
│
│
"Send an email"
"Process payment"
│
"Run inference on
│
local LLM"
│
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│
INTENT ROUTING LAYER (3-tier + custom)
│
│
│
│┌─────────────┐││ 1. Keyword│──→│ 2. Intent│──→│ 3. Fuzzy Scoring (name/desc/││││││││ 130+ mappings││ (delegated) ││││
│└─────────────┘└─────────────┘└─────────────────────────────────┘│
│▲▲││││└─ Loads from
Map
┌─────────────┐
│
Engine
┌─────────────────────────────────┐
│
feat) (fallback, never
│
│
│
throws)
│
│
└─ Custom intent handlers plug in here
│.lists/provider_keywords.json
│(inline fallback + adaptive learning)
│
│
│
│
│
│┌─────────────────────────────────────────────────────────────────────┐
││ CUSTOM INTENT HANDLERS (your domain logic)
││
• patient_notification → HipaaMail
││
• deploy_notification → Slack/Teams
││
• fraud_alert → PagerDuty + SMS
│└─────────────────────────────────────────────────────────────────────┘
│
│
│
│
│
│
│
│
│
│
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│
MATCHED PROVIDER CANDIDATES
│
│
│
│
[sendgrid, mailgun, postmark, resend, brevo]
│
│
│
│
→ Ranked by learned preference (per-user → sector → default)
│
│
│
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│
AUTO-CONNECT GATE SEQUENCE (per provider, extensible)
│
│
│
│┌─────────┐┌─────────┐│
││ Region│──│ Config
┌─────────┐
│──│ Consent │──│[CUSTOM ]│──│ Confirm │
┌─────────┐
┌─────────┐
│
││ Check││ Check││ Check││GATE││ Gate││
││││ (Key││││(your││ (Policy ││
││││ Vault→││││ logic)││ Engine) ││
││││ env)││││││└─────────┘└─────────┘└─────────┘└─────────┘│skipskipskipskip││
└─────────┘
│
│
skip
│
│▲│
│││
│┌──────────────┘│
││
│
│▼│┌─────────────────────┐
│
││CUSTOM GATES││
││• hipaa_validation││
││• data_classification││
││• compliance_check││• cost_center_budget ││└─────────────────────┘
│
│
│
│
│
│
│
│┌─────────┐
││
┌─────────┐
┌─────────┐│
│ Internet│──│ Circuit │──│ Rate│──│ Connect ││
│ Gate││ Breaker ││ Limit││ Test││
││││ (per│ (per││ (health ││
││││ identity││ identity││ endpoint││
││││+provider)││+provider)││└─────────┘└─────────┘└─────────┘│skipskip
│
┌─────────┐
skip
│
│ )
│
└─────────┘
│
│
fail → learn "failure"│
success → learn "success"│
│
│
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│
RESULTS + LEARNING
│
│
│
│connected:[{ id: 'sendgrid', message: 'Connected' }]│
│skipped:[{ id: 'mailgun', reason: 'Not configured' }]│
│failed:[{ id: 'postmark', error: 'HTTP 401' }]│
│
│
│
→ Pattern learner:
alice::acme::fintech → prefers sendgrid for "email"
│
│
→ Learning engine:
anonymized pattern: fintech sector → sendgrid success
│
│
│
└─────────────────────────────────────────────────────────────────────────────┘
Composite Identity (12 Dimensions)
┌─────────────────────────────────────────────────────────────────────────────┐
│
│
│
alice :: acme-corp :: engineering :: api-gateway :: fintech :: admin
│
│
│
│
userId
tenantId
orgId
projectId
sector
role
│
│
│
│
:: alice.smith :: sess-abc
│
│
│
│
username
sessionId
│
│
│
│
SHA-256 → "a3f7b2d9e1c8a4b5" (first 16 chars, env-driven)
│
│
│
│Storage key:
│
│alice#acme-corp#engineering#api-gateway#fintech#admin#a3f7...│
│(6 dims from STORAGE_IDENTITY_MASK + hash)│
│
│
└─────────────────────────────────────────────────────────────────────────────┘
Env Cascade (5 Sources)
┌─────────────────┐
│process.env
│(highest prio) │
┌─────────────────┐
┌─────────────────┐
│────→│ .env / env.json │────→│
└─────────────────┘
│
/ .env.bak
│
└─────────────────┘
config.json
│
│
│
└─────────────────┘
│
▼
┌─────────────────┐
│
fallback
┌─────────────────┐
│←────│orchestrator_│
defaults.json│
│param││
│(lowest prio)││
└─────────────────┘
│
└─────────────────┘
Flat Storage Structure
data/
├── audit/
│
└── provider_auto_connect/
│├── pac_alice#acme-corp#eng#api#fintech#admin#a3f7...jsonl
│├── pac_bob#acme-corp#sales#crm#fintech#user#b2c0...jsonl
│├── pac_alice#acme-corp#eng#api#fintech#admin#a3f7...jsonl.1720406400000.gz
│└── archive/
│
└── consents/
├── consents_alice#acme-corp#eng#api#fintech#admin#a3f7...json
└── consents_bob#acme-corp#sales#crm#fintech#user#b2c0...json
**
Code Snippets
Minimal Standalone Usage**
const pac = require('./provider_auto_connect');
// Just check what's available
const status = await pac.getAllProviderStatus({ userId: 'alice' });
// status.openai -> { configured: true, consent: true, enabled: true }
With Intent Routing
const result = await pac.routeIntentToProviders(
"Process a payment for $50",
{ userId: 'alice', sector: 'fintech', role: 'admin' },
{ autoConnect: true }
);
if (result.connected.length > 0) {
const stripe = result.connected.find(c => c.id === 'stripe');
_debug('stripe_connected', { message: stripe.message });
// "Stripe connected successfully"
}
Custom Provider Registration
const provider = pac.registerCustomProvider({
name: 'InternalAnalytics',
requiredCredentials: ['INTERNAL_ANALYTICS_KEY'],
testEndpoint: 'https://analytics.internal/health',
features: ['tracking', 'reporting'],
keywords: ['internal', 'analytics', 'metrics']
}, { autoConnect: true, identity: buildCompositeIdentity({ userId: 'alice' }) });
Full Service Instance with Gated Logging
const { getServiceInstance } = require('./provider_auto_connect');
const service = getServiceInstance({
userId: 'alice',
tenantId: 'acme',
sector: 'fintech',
role: 'admin'
});
// Events flow through PME, not console
service.on('provider:auto_connected', ({ providerId, latencyMs }) => {
_debug('auto_connected', { providerId, latencyMs });
const results = await service.autoConnect({
onConnect: (id, msg) => _debug('connected', { providerId: id, message: msg }),
onSkip: (id, reason) => _debug('skipped', { providerId: id, reason }),
onError: (id, err) => _debug('error', { providerId: id, error: err.message })
});
_debug('summary', {
connected: results.connected.length,
skipped: results.skipped.length,
failed: results.failed.length
});
PME Audit Event Example
// Every gate in the auto-connect loop emits structured events//
await structuredLogger.append({
event: 'provider_gate_result',
identity: compositeKey,
providerId: 'stripe',
gate: 'circuit_breaker',
result: 'passed',
timestamp: Date.now()
});
// Standalone fallback writes per-identity JSONL//
await writeIdentityJsonl(compositeKey, {
event: 'provider_gate_result',
providerId: 'stripe',
gate: 'circuit_breaker',
result: 'passed'
});
Learning from Connection Outcomes
Every success and failure teaches the system which providers work best for which identities. Three
learning layers operate in parallel:
// Layer 1: Auto-Pattern Learner (per-user preferences)
// "Alice in fintech prefers SendGrid for email"//
await userPreferenceStore.learn({
identity: compositeKey,
// alice::acme::fintech
context: { intent: 'email', sector: 'fintech' },
providerId: 'sendgrid',
outcome: 'success',
latencyMs: 245,
timestamp: Date.now()
});
// Layer 2: Dynamic Learning Engine (system-wide anonymized patterns)
"Fintech sector → SendGrid has 94% success rate for email"
await sectorPatternStore.learn({
identity: compositeKey,
context: { sector: 'fintech', providerId: 'sendgrid', intent: 'email' },
outcome: 'success',
anonymize: true,
// strips userId, keeps sector/role/org
weight: 1.0
});
// Layer 3: System-Wide Learner (cross-tenant patterns)//
// "Enterprise licenses in regulated sectors prefer providers with SOC2"//
await globalPatternStore.learn({
context: { licenseType: 'enterprise', sector: 'fintech', compliance: 'soc2' },
providerId: 'sendgrid',
outcome: 'success',
anonymize: true,
aggregation: 'count'
// increments counter, no PII
});
Building on Top of Learned Preferences
The learning layers aren’t write-only. You retrieve patterns to drive decisions:
// Query per-user preference before routing
const userPreference = await userPreferenceStore.retrieve({
identity: compositeKey,
context: { intent: 'email' }
});
// Returns: { providerId: 'sendgrid', confidence: 0.94, lastUsed: '2026-07-08T01:00:00Z' }
// Query system-wide pattern for fallback
const sectorPattern = await sectorPatternStore.retrieve({
context: { sector: 'fintech', intent: 'email' }
});
// Returns: [
//{ providerId: 'sendgrid', successRate: 0.94, sampleSize: 1247 },
//{ providerId: 'mailgun', successRate: 0.89, sampleSize: 892 }
// ]
// Use learned data to rank provider candidates
const ranked = await rankProvidersByPreference({
candidates: ['sendgrid', 'mailgun', 'postmark'],
identity: compositeKey,
intent: 'email'
});
// Returns: [
//{ id: 'sendgrid', rank: 1, reason: 'user_preference_94%' },
//{ id: 'mailgun', rank: 2, reason: 'sector_fallback_89%' },
//{ id: 'postmark', rank: 3, reason: 'default_order' }
// ]
Extending with Custom Dimensions
The learning system accepts any dimensions you define. No hardcoded lists:
// Your runtime adds a custom dimension: deploymentEnvironment//
await userPreferenceStore.learn({
identity: compositeKey,
context: {
intent: 'email',
sector: 'fintech',
deploymentEnvironment: 'production'
// your custom dimension
},
providerId: 'sendgrid',
outcome: 'success'
});
// Retrieve with that dimension//
const prodPreference = await userPreferenceStore.retrieve({
identity: compositeKey,
context: {
intent: 'email',
deploymentEnvironment: 'production'
}
});
// Returns preference scoped to production environment
Learning Lifecycle
Learned patterns have retention policies matching audit logs:
┌─────────────────────────────────────────────────────────────┐
│
LEARNING DATA LIFECYCLE
│
│
│
│Pattern Learner (per-user)│
│├── Hot: 0-30d│
│├── Warm: 30-90d → JSONL, loaded on cache miss│
│└── Cold: 90d+│
→ SQLite, queried on every route
→ Gzipped archive, rarely accessed
│
│
│Learning Engine (system-wide)
│├── Hot: 0-30d→ SQLite, aggregated counters
│└── 30d+→ Pruned (anonymized aggregates kept)
│
│
│
│
│
│System-Wide Learner
│└── Permanent
→ Anonymized counts only, no PII ever
│
│
│
│
└─────────────────────────────────────────────────────────────┘
- Building on Top of the Provider Layer The service isn’t a black box. Every layer is designed for extension. Here is how you hook into each part:
Custom Provider with Bespoke Test Logic
const provider = pac.registerCustomProvider({
name: 'InternalLLM',
requiredCredentials: ['INTERNAL_LLM_API_KEY'],
testEndpoint: 'http://internal-llm.local/health',
features: ['chat', 'embeddings'],
keywords: ['internal', 'llm', 'private'],
// Override the default connection test
testConnection: async (credentials, identity) => {
const res = await fetch('http://internal-llm.local/v1/models', {
headers: { Authorization: `Bearer ${credentials.INTERNAL_LLM_API_KEY}` }
});
if (!res.ok) throw new Error(`Model list failed: ${res.status}`);
const models = await res.json();
return {
ok: models.data.length > 0,
message: `${models.data.length} models available`,
metadata: { modelCount: models.data.length }
};
}
}, { autoConnect: true, identity: runtimeContext });
**Custom Gate in the Auto-Connect Loop**
// Add a compliance gate that runs after consent but before connection test
pac.addGate('compliance_check', {
position: 'after_consent',
// before_connect, after_region, etc.
handler: async (provider, identity, context) => {
if (identity.sector === 'healthcare' && !provider.features.includes('hipaa')) {
return { skip: true, reason: 'HIPAA compliance required' };
}
return { skip: false };
}
});
// The gate appears in the sequence automatically:
// Region → Config → Consent → Compliance → Confirm → Internet → Circuit → Rate → Connect
**Custom Intent Handler**
// Register a semantic handler that overrides keyword matching for specific intents//
pac.registerIntentHandler('deploy_notification', {
match: (intentText, context) => {
// Your custom NLP or regex
const isDeploy = /deploy|release|ship/i.test(intentText);
const hasTeam = /team|channel|slack/i.test(intentText);
return isDeploy && hasTeam ? 0.95 : 0.0;
},
resolve: async (intentText, identity, context) => {
// Return ordered provider preferences for this intent
const learned = await userPreferenceStore.retrieve({
identity,
context: { intent: 'deploy_notification' }
});
return [
{ providerId: learned?.providerId || 'slack', confidence: 0.92 },
{ providerId: 'teams', confidence: 0.78 }
];
}
});
**
Custom Storage Backend**
// Swap the default SQLite/JSONL for your own store
pac.useStorageBackend({
name: 'redis_audit_store',
write: async (identity, event) => {
const key = `audit:${identity.hash}:${Date.now()}`;
await redis.setex(key, 2592000, JSON.stringify(event)); // 30d TTL
},
read: async (identity, options) => {
const pattern = `audit:${identity.hash}:*`;
const keys = await redis.keys(pattern);
const events = await redis.mget(keys);
return events.map(e => JSON.parse(e)).filter(e =>
e.timestamp >= (options.since || 0)
);
},
archive: async (identity, cutoffTimestamp) => {
// Your cold-storage logic: S3, Glacier, etc.//
const oldKeys = await redis.keys(`audit:${identity.hash}:*`);
const oldEvents = await redis.mget(oldKeys);
await s3.putObject({
Bucket: 'audit-archive',
Key: `provider-auto-connect/${identity.hash}/${cutoffTimestamp}.jsonl.gz`,
Body: gzip(oldEvents.join('\n'))
});
await redis.del(oldKeys);
}
});
**Custom Identity Dimensions**
// Extend the 12 built-in dimensions with your own//
const identity = buildCompositeIdentity({
userId: 'alice',
tenantId: 'acme',
sector: 'fintech',
role: 'admin',
// Your custom dimensions
deploymentEnvironment: 'production',
costCenter: 'eng-infra',
dataClassification: 'restricted'
});
// These flow through the composite key automatically://
// alice::acme::...::production::eng-infra::restricted//
// Use them in gates, learning, and routing//
pac.addGate('data_classification', {
position: 'before_connect',
handler: async (provider, identity) => {
if (identity.dataClassification === 'restricted' &&
!provider.features.includes('encryption_at_rest')) {
return { skip: true, reason: 'Encryption at rest required for restricted data' };
}
return { skip: false };
}
});
**Custom Event Hooks Beyond onConnect/onSkip/onError**
const service = getServiceInstance(identity);
// All built-in events//
service.on('provider:matched', ({ providerId, matchScore }) => {
_debug('matched', { providerId, matchScore });
});
service.on('provider:gate_passed', ({ providerId, gate, latencyMs }) => {
_debug('gate_passed', { providerId, gate, latencyMs });
});
service.on('provider:gate_failed', ({ providerId, gate, reason }) => {
_debug('gate_failed', { providerId, gate, reason });
});
service.on('provider:learned', ({ providerId, outcome, confidence }) => {
_debug('learned', { providerId, outcome, confidence });
});
// Define your own event and emit from custom gates//
service.on('provider:compliance_flagged', ({ providerId, regulation }) => {
alertSecurityTeam({ providerId, regulation, identity: compositeKey });
});
**Composing Everything Together**
// A complete custom integration: healthcare-compliant email provider//
const healthcareEmail = pac.registerCustomProvider({
'HipaaMail',
requiredCredentials: ['HIPAA_MAIL_API_KEY', 'HIPAA_MAIL_SIGNING_KEY'],
features: ['email', 'hipaa', 'encryption_at_rest', 'audit_trail'],
keywords: ['healthcare', 'hipaa', 'patient', 'medical'],
testConnection: async (creds, identity) => {
const res = await fetch('https://hipaamail.local/compliance/status', {
headers: { 'X-API-Key': creds.HIPAA_MAIL_API_KEY }
});
const status = await res.json();
return {
ok: status.hipaaCertified && status.encryptionVerified,
message: status.hipaaCertified ? 'HIPAA certified' : 'Certification expired'
};
}
});
pac.addGate('hipaa_validation', {
position: 'before_connect',
handler: async (provider, identity) => {
if (identity.sector === 'healthcare' && provider.name !== 'HipaaMail') {
return { skip: true, reason: 'Non-HIPAA provider blocked for healthcare sector' };
}
return { skip: false };
}
});
pac.registerIntentHandler('patient_notification', {
match: (text) => /patient|appointment|prescription/i.test(text) ? 0.98 : 0,
resolve: async (text, identity) => [
{ providerId: 'HipaaMail', confidence: 0.99 }
]
});
const results = await service.autoConnect({
intent: 'Send patient appointment reminder',
onConnect: (id, msg) => _debug('hipaa_connected', { providerId: id }),
onSkip: (id, reason) => _debug('hipaa_skipped', { providerId: id, reason })
});
// results.connected -> [{ id: 'HipaaMail', message: 'HIPAA certified' }]
Extension Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│
EXTENSION POINTS (6 layers)
│
│
│
│┌─────────────────────────────────────────────────────────────────────┐││ 1. CUSTOM PROVIDERS
│
││registerCustomProvider({ name, testEndpoint, testConnection })││
││└── Plugs into: Provider Registry (234 + unlimited custom)││
│└─────────────────────────────────────────────────────────────────────┘│
│
│
│││
│▼│
│┌─────────────────────────────────────────────────────────────────────┐│
││ 2. CUSTOM GATES│
││addGate('name', { position, handler })││└── Injects into: Auto-Connect Gate Sequence (9 + custom)││
│└─────────────────────────────────────────────────────────────────────┘│
│
│
│
│││
│▼│
│┌─────────────────────────────────────────────────────────────────────┐│
││ 3. CUSTOM INTENT HANDLERS││
││registerIntentHandler('name', { match, resolve })││
││└── Plugs into: Intent Routing Layer (3-tier + custom)││
│└─────────────────────────────────────────────────────────────────────┘│
│││
│▼│
│┌─────────────────────────────────────────────────────────────────────┐│
││ 4. CUSTOM STORAGE BACKENDS││
││useStorageBackend({ name, write, read, archive })││
││└── Replaces: SQLite/JSONL (default)││
│└─────────────────────────────────────────────────────────────────────┘│
││
│▼
│
│
│┌─────────────────────────────────────────────────────────────────────┐││ 5. CUSTOM IDENTITY DIMENSIONS││buildCompositeIdentity({ ...yourDimensions })││└── Extends: 12 built-in → N custom (no hardcoded limit)││
│└─────────────────────────────────────────────────────────────────────┘│
││
│▼
│
│
│
│
│
│
│
│┌─────────────────────────────────────────────────────────────────────┐
│
││ 6. CUSTOM EVENT HOOKS││service.on('provider:your_event', handler)││└── Emits from: Custom gates, custom providers, custom intents││
│└─────────────────────────────────────────────────────────────────────┘│
│
││
│▼
│
│
│
│
│
│┌─────────────────────────────────────────────────────────────────────┐
││
││
│└─────────────────────────────────────────────────────────────────────┘
PME AUDIT STREAM
(all extension points emit structured events)
│
││
││
│
└─────────────────────────────────────────────────────────────────────────────┘
The Numbers
MetricValue
Functions/classes70
Exported symbols50
Metric Value
────────────────────────────────────────────────────────────────────
Built-in providers 234
Provider categories 24
Identity dimensions 12
Env vars 40+
Entry points 21
Infrastructure modules 23
PII redaction patterns 16+
Keyword mappings 130+ (externalizable)
Debug env vars 1 (DEBUG_ENABLED)
PME event types 8 (one per gate)
Learning layers 3 (per-user, system-wide, cross-tenant)
Learning dimensions 9+ (identity + custom)
Extension points 6 (provider, gate, intent, storage, identity,
events)
────────────────────────────────────────────────────────────────────
┌────────────────────────────────────────┐
│ SOVEREIGN CORE RUNTIME │
│ (Fetch, Dynamic Loader, Registry) │
└───────────────────┬────────────────────┘
│
[Dispatches Intent + 12D Composite Identity]
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ PROVIDER AUTO-CONNECT LAYER │
│ │
│ ┌───────────────────────────┐ ┌────────────────────────────┐ │
│ │ 1. 12-DIMENSIONAL MASK │ │ 2. OFFLINE-FIRST TREE │ │
│ │ Flat Directory Storage │ │ Check Local Ecosystem │ │
│ │ (No Nested File Trails) │ │ (Ollama, Chroma, MinIO...) │ │
│ └─────────────┬─────────────┘ └─────────────┬──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌───────────────────────────┐ ┌────────────────────────────┐ │
│ │ 3. DYNAMIC REGISTRY │ │ 4. EMISSION GATE │ │
│ │ 234+ Manifest Templates │ │ Check INTERNET_ENABLED=true│ │
│ │ & Custom Configurations │ │ Cascaded Configuration Env │ │
│ └─────────────┬─────────────┘ └─────────────┬──────────────┘ │
│ │ │ │
│ └───────────────────┬─────────────────┘ │
│ │ │
│ [Secure Ephemeral Execution Bubble] │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ DECLARATIVE PAYLOAD TRANSLATOR │ │
│ │ (JSON Matrix Mapping Engine) │ │
│ └────────────────────┬───────────────────┘ │
└─────────────────────────────────────┼────────────────────────────────────┘
│
[Isolated Proxy Data Egress]
│
▼
┌──────────────────────────────────────┐
│ EXTERNAL CLIENT SERVICE PIPES │
│ (User's Stripe, Twilio, OpenAI...) │
└──────────────────────────────────────┘
Why This Matters
Before this service, our integration code was write-once, debug-forever. Now it’s the opposite:
• Adding a new provider? We add one object to the provider registry. The connect loop doesn’t
change.
• Changing a timeout? We set TEST_TIMEOUT_MS=10000. No deploy needed.
• New sector needs different policies? Our composite identity handles it. No if (sector ===
'fintech') anywhere in our codebase.
• Running fully offline? Our internal runtime (Part 2) needs zero external APIs. But when you
want cloud features, our local providers (Ollama, LM Studio, MinIO, Chroma) still work with
INTERNET_ENABLED=false — no accidental cloud calls.
• Audit requirements? Every event is PME-logged + per-identity JSONL. No shared audit DB.
• Querying by tenant? Our flat dimension-encoded filenames make it trivial: fs.readdirSync(dir).filter(f
=> f.includes('#acme-corp#'))
We’ve open-sourced the patterns for the community. The patterns — env cascade, composite identity,
flat dimension-encoded storage, delegation with fallback, intent routing, lifecycle management — are
portable to any service that needs to manage external integrations at scale.
What I Learned
Building this service taught us three things we didn’t expect:
The env cascade eliminated more bugs than tests did. When every timeout, threshold, and
endpoint is env-driven, “it works on my machine” disappears. Deployment surprises dropped to near
zero once we stopped hardcoding.
Composite identity is overkill until it isn’t. We started with userId. Then needed tenantId. Then
sector.
Then role. By the time we hit twelve dimensions, we realized the model should have been
composite from day one — retrofitting identity isolation across 70 functions was painful.
Flat storage beats deep nesting for audit trails. We tried hierarchical directories (data/audit/
2026/07/08/alice.jsonl).
Querying by tenant required recursive walks. Flat dimension-encoded file-
names turned fs.readdirSync().filter() into a query engine.
The rest — intent routing, learning layers, custom gates — were optimizations we added after the pain
justified the complexity. We didn’t build them on day one, and we wouldn’t recommend anyone else does
either.
The next post in this series covers how we handle memory policy:
Open For All Discussions:
GLA SYSTEMS:
ABSOLUTE SOVEREIGNTY!
Top comments (0)