@tealbrick/provider-transport 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tealbrick contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,2 @@
+Independently authored Teal Brick transport extracted from @tealbrick/voice
+for reuse by Voice and Vision. No Kybernesis implementation is copied.

package/README.md

@@ -0,0 +1,9 @@
+# @tealbrick/provider-transport
+
+Shared trusted-runtime transport for Teal Brick Voice and Vision. Node 24+, no harness dependency.
+
+Exports exact endpoint/credential policy enforcement, credential resolution scoped to organization and agent, redirect refusal, timeout validation, abort-aware waits and bounded stream reads. It performs no user authentication: domain handlers must authenticate and authorize before calling `upstream`.
+
+Use `createProviderTransport({binding,endpoints,resolveCredential,errorPrefix})`, then `upstream({url,credentialRef},body,signal,contentType)`. HTTPS is required except explicitly approved loopback HTTP. Anonymous access must be explicitly approved. Never source endpoint policies or the credential resolver from an untrusted request. No retries or response persistence are performed.
+
+This is portfolio support code, not a separate miniapp. Domain protocols remain owned by their packages.

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+export interface EndpointPolicy {
+    url: string;
+    credentialRefs?: readonly string[];
+    allowAnonymous?: boolean;
+    allowLoopback?: boolean;
+}
+export interface ProviderEndpoint {
+    url: string;
+    credentialRef?: string;
+}
+export interface ProviderOptions {
+    binding: {
+        org: string;
+        agent: string;
+    };
+    endpoints: readonly EndpointPolicy[];
+    resolveCredential?: (binding: {
+        reference: string;
+        url: string;
+        org: string;
+        agent: string;
+    }) => string | Promise<string>;
+    fetch?: typeof fetch;
+    /** Stable public error-code namespace, not provider exception text. */
+    errorPrefix?: string;
+}
+export declare class ProviderFailure extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+export declare function endpointUrl(value: unknown, allowLoopback?: boolean): string;
+export declare function providerTimeout(value?: number): number;
+export declare function boundedWait<T>(pending: Promise<T>, signal: AbortSignal): Promise<T>;
+export declare function bytes(body: ReadableStream<Uint8Array> | null, limit: number, signal: AbortSignal, tooLargeCode?: string): Promise<Uint8Array<ArrayBuffer>>;
+/** Shared transport only. Callers must authenticate and authorize before calling upstream. */
+export declare function createProviderTransport(options: ProviderOptions): {
+    policy: (endpoint: ProviderEndpoint) => string;
+    upstream: (endpoint: ProviderEndpoint, body: BodyInit, signal: AbortSignal, contentType?: string) => Promise<Response>;
+};

package/dist/index.js

@@ -0,0 +1,128 @@
+export class ProviderFailure extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(code);
+        this.status = status;
+        this.code = code;
+    }
+}
+export function endpointUrl(value, allowLoopback = false) {
+    if (typeof value !== "string" || !value.trim() || value.length > 2048 || /[\u0000-\u0020\u007f]/.test(value))
+        throw new Error("invalid_provider_endpoint");
+    const url = new URL(value);
+    const local = allowLoopback && url.protocol === "http:" && ["127.0.0.1", "[::1]", "localhost"].includes(url.hostname);
+    if ((!local && url.protocol !== "https:") || url.username || url.password || url.search || url.hash)
+        throw new Error("invalid_provider_endpoint");
+    return url.href;
+}
+export function providerTimeout(value = 30000) {
+    if (!Number.isInteger(value) || value < 1 || value > 120000)
+        throw new Error("invalid_provider_timeout");
+    return value;
+}
+export async function boundedWait(pending, signal) {
+    if (signal.aborted) {
+        void pending.catch(() => { });
+        throw signal.reason;
+    }
+    let abort = () => { };
+    const cancelled = new Promise((_, reject) => {
+        abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+    });
+    try {
+        return await Promise.race([pending, cancelled]);
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+    }
+}
+export async function bytes(body, limit, signal, tooLargeCode = "provider_payload_too_large") {
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new Error("invalid_provider_size_limit");
+    if (!body) {
+        signal.throwIfAborted();
+        return new Uint8Array();
+    }
+    const reader = body.getReader();
+    let size = 0;
+    const chunks = [];
+    const cancel = () => { void reader.cancel().catch(() => { }); };
+    signal.addEventListener("abort", cancel, { once: true });
+    try {
+        signal.throwIfAborted();
+        for (;;) {
+            const next = await reader.read();
+            signal.throwIfAborted();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > limit) {
+                cancel();
+                throw new ProviderFailure(413, tooLargeCode);
+            }
+            chunks.push(next.value);
+        }
+        const result = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return result;
+    }
+    finally {
+        signal.removeEventListener("abort", cancel);
+        reader.releaseLock();
+    }
+}
+/** Shared transport only. Callers must authenticate and authorize before calling upstream. */
+export function createProviderTransport(options) {
+    const binding = Object.freeze({ ...options.binding });
+    const policies = options.endpoints.map(p => ({ ...p, url: endpointUrl(p.url, p.allowLoopback), credentialRefs: [...(p.credentialRefs ?? [])] }));
+    if (new Set(policies.map(p => p.url)).size !== policies.length)
+        throw new Error("duplicate_provider_endpoint_policy");
+    const prefix = options.errorPrefix ?? "provider";
+    if (!/^[a-z][a-z0-9_]{0,40}$/.test(prefix))
+        throw new Error("invalid_provider_error_prefix");
+    function fail(status, suffix) { throw new ProviderFailure(status, `${prefix}_${suffix}`); }
+    function policy(endpoint) {
+        const url = endpointUrl(endpoint.url, true);
+        const found = policies.find(p => p.url === url);
+        if (!found || (endpoint.credentialRef ? !found.credentialRefs.includes(endpoint.credentialRef) : !found.allowAnonymous))
+            fail(503, "endpoint_not_approved");
+        return url;
+    }
+    async function upstream(endpoint, body, signal, contentType) {
+        const url = policy(endpoint);
+        let token;
+        if (endpoint.credentialRef) {
+            try {
+                token = await boundedWait(Promise.resolve(options.resolveCredential?.({ ...binding, reference: endpoint.credentialRef, url })), signal);
+            }
+            catch {
+                fail(503, "credential_unavailable");
+            }
+            if (!token || /[\s\u0000-\u001f\u007f]/.test(token))
+                fail(503, "credential_unavailable");
+        }
+        let response;
+        try {
+            signal.throwIfAborted();
+            response = await boundedWait((options.fetch ?? fetch)(url, {
+                method: "POST", redirect: "error", signal,
+                headers: { ...(token ? { authorization: `Bearer ${token}` } : {}), ...(contentType ? { "content-type": contentType } : {}) }, body,
+            }), signal);
+        }
+        catch {
+            return fail(signal.aborted ? 504 : 502, signal.aborted ? "timeout_or_cancelled" : "provider_unavailable");
+        }
+        if (!response.ok) {
+            void response.body?.cancel().catch(() => { });
+            fail(502, "provider_rejected");
+        }
+        return response;
+    }
+    return { policy, upstream };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@tealbrick/provider-transport",
+  "version": "0.1.0",
+  "description": "Shared bounded provider transport and endpoint credential policy for Teal Brick adapters",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Doppelabs/tealbrick-packages.git",
+    "directory": "packages/provider-transport"
+  }
+}