​

Network Egress Policy & Guardrails via AsyncLocalStorage (ASL)

​

1. Core Principles & Guarantees

1. Policy Activation & Default Deny: Unconfigured workflows have no egress enforcement (unrestricted). When a network policy is declared on a flow or step, enforcement activates and defaults to denying external outbound network access unless explicitly authorized by step-level or flow-level allowlists.
2. Flow Supersedes Step (Outer Envelope Narrowing): The Flow defines the outer security perimeter. A Step can only narrow permissions within what the Flow permits; it cannot unilaterally expand or bypass the Flow allowlist.
3. Multi-Layer Egress Interception: Outbound requests are governed across three distinct runtime layers:
   • Native globalThis.fetch (Fetch API, Undici)
   • node:http and node:https (request and get, Axios, Got, legacy clients)
   • node:net.Socket.prototype.connect (Raw TCP/TLS connections)
4. Localhost & Loopback Configuration: When network policy is active, allowLocalhost defaults to false. When enabled (allowLocalhost: true), loopback addresses (localhost, 127.0.0.1, ::1, 0.0.0.0) and local Unix domain socket IPC (allowUnixSockets) are permitted, preserving local database pools, test mock servers, and container-local sidecars.
5. Zero Concurrency Cross-Talk: Handled via AsyncLocalStorage. When steps execute concurrently in parallel, allSettled, or map, each step runs in its own isolated ASL context. Background host operations (e.g. server health checks, connection pool pings) remain unaffected.

​

2. Architecture & Runtime Context Propagation

​

2.1 The Concurrency Challenge in Node.js

​

2.2 AsyncLocalStorage Context Isolation

​

3. Step-Level Declarative API

​

3.1 step.allowNetwork(hosts)

import { Step } from '@siglo/core';

// Whitelist specific domains and wildcard patterns
const chargeCustomer = Step.create('charge', async ({ amount }) => {
    const res = await fetch('https://api.stripe.com/v1/charges', {
        method: 'POST',
        headers: { Authorization: 'Bearer sk_test_...' },
        body: JSON.stringify({ amount }),
    });
    return await res.json();
}).allowNetwork(['api.stripe.com', '*.stripe.network']);

​

3.2 step.denyNetwork()

const calculateDiscounts = Step.create('discount', ({ cart }) => {
    // Pure computation: cannot make any external HTTP or socket calls
    return { discountedTotal: applyCoupons(cart) };
}).denyNetwork();

​

3.3 step.networkPolicy(policy)

const syncProfile = Step.create('sync', async ({ userId }) => {
    return await fetch(`https://api.github.com/users/${userId}`);
}).networkPolicy({
    allowedHosts: ['api.github.com'],
    defaultPolicy: 'deny',
    allowLocalhost: false, // Defaults to false when policy is active
});

​

4. Flow-Level Declarative API

​

4.1 flow(...).networkPolicy(policy)

import { Step, flow } from '@siglo/core';

const fetchUser = Step.create('fetchUser', async () => { ... })
    .allowNetwork(['api.github.com']);

const chargeCard = Step.create('chargeCard', async () => { ... })
    .allowNetwork(['api.stripe.com']);

export const onboardingFlow = flow(fetchUser, chargeCard)
    .networkPolicy({
        defaultPolicy: 'deny',
        allowedHosts: ['api.github.com', 'api.stripe.com'],
        allowLocalhost: false
    });

​

4.2 Per-Execution Run Overrides

await onboardingFlow.run(payload, {
    networkPolicy: {
        allowedHosts: ['api.stripe.com'], // Disallows api.github.com for this specific run
    },
});

​

5. Precedence Rules: Flow Supersedes Step

​

6. Pattern Matching Grammar

​

7. Multi-Layer Interceptors

1. Native globalThis.fetch Interceptor:
   • Inspects target input (string, URL, or Request object).
   • Resolves target host and checks the active ASL store.
   • Throws NetworkPolicyViolationException synchronously before any socket is created.
   • Sets an internal validated socket flag so underlying Node HTTP socket pools avoid duplicate verification overhead.
2. node:http and node:https Interceptor:
   • Intercepts http.request, http.get, https.request, and https.get.
   • Protects libraries relying on Node’s native HTTP client (e.g. Axios, Got, Node core).
   • If blocked, emits an 'error' event with NetworkPolicyViolationException on the client request stream.
3. node:net.Socket.prototype.connect Interceptor:
   • Deepest safety net preventing raw TCP/TLS connections to unauthorized endpoints.
   • Automatically bypasses local Unix domain socket paths and sockets already validated by higher-level HTTP interceptors.
   • Destroys unauthorized sockets immediately with NetworkPolicyViolationException.

​

8. Exception & Error Model: NetworkPolicyViolationException

export class NetworkPolicyViolationException extends SigloError {
    readonly requestedUrl: string;
    readonly requestedHost: string;
    readonly allowedHosts: (string | RegExp)[];
}

​

Non-Retryable Classification

• phase: 'action' (or phase: 'validation' when triggered during Step.spec validation, transforms, or translations; phase: 'before' / phase: 'after' in hooks)
• retryable: false

​

9. Concurrency & Parallel Branch Isolation

import { Step, flow, parallel } from '@siglo/core';

const callStripe = Step.create('stripe', async () => {
    return await fetch('https://api.stripe.com/v1/charges');
}).allowNetwork(['api.stripe.com']);

const callSendGrid = Step.create('sendgrid', async () => {
    return await fetch('https://api.sendgrid.com/v3/mail/send');
}).allowNetwork(['api.sendgrid.com']);

// Even though both run concurrently on the single event loop,
// callStripe cannot access sendgrid.com, and callSendGrid cannot access stripe.com!
const concurrentFlow = flow(parallel([callStripe, callSendGrid])).networkPolicy({
    allowedHosts: ['api.stripe.com', 'api.sendgrid.com'],
});

​

10. Graph Inspection & Visualization

const node = workflow.toGraph();
console.log(node.metadata?.networkPolicy);
// Outputs: { enabled: true, allowedHosts: ['api.stripe.com'], defaultPolicy: 'deny' }

const metrics = workflow.inspect();
console.log(metrics);

​

11. Related Topic Guides

• 📜 Execution Semantics Contract
• 🧱 API Reference: Step Methods
• 🌊 API Reference: Flow Instance Methods
• 🛡️ Retries, Timeouts, and Cancellation
• 🚨 Error Model & Exception Hierarchy
• 🧪 Deterministic Testing Guide