@skaile/transform-proxy 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First release: transform contract, chain composition, per-session state and facts, the HTTP proxy with the Anthropic Messages walker, and the `skaile-transform-proxy` CLI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthias Ortegro
+
+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/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @skaile/transform-proxy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A same-protocol passthrough HTTP proxy. A model client points its base URL at the proxy; the proxy runs every text leaf of the request through a chain of transforms (outbound), forwards the request with the client's own auth, and restores the reply (inbound), in JSON and in streamed SSE.
+
+Anthropic in is Anthropic out. Only text fields are rewritten; everything else is forwarded byte for byte.
+
+## Headers
+
+| Header | Purpose |
+|---|---|
+| `x-skaile-transform-upstream` | Upstream base URL, for example `https://api.anthropic.com`. Required. |
+| `x-skaile-transform-session` | Session id. Defaults to `default`. Transform state is kept per session. |
+| `x-skaile-transform-pipeline` | Pipeline name. Defaults to `defaultPipeline`; without either, the request is refused. |
+| `x-skaile-transform-token` | Client token. Required when a token is configured. |
+
+The proxy strips all four headers before forwarding. Every other header, including `Authorization` and `x-api-key`, is relayed unchanged.
+
+## Routes
+
+| Path suffix | Handling |
+|---|---|
+| `POST …/messages` | Anthropic request and response: request rewritten, JSON reply and SSE stream restored. |
+| `POST …/messages/count_tokens` | Request rewritten; the response passes through untouched. |
+| `GET …/models` | Passthrough. |
+| anything else (chat completions, responses, embeddings) | 404 `unsupported_route`. |
+
+OpenAI chat and responses walkers are not implemented yet. Embeddings are refused on purpose: a vector of pseudonymized input cannot be restored.
+
+## Refusals
+
+- Attachments (image, document, file parts) are refused with 400 `unsupported_content`. Nothing is sent upstream.
+- Unknown routes, pipelines and upstreams are refused before any body is read or transform is built.
+- A transform that throws refuses the request with 502 `transform_failed`. Nothing is sent upstream.
+- Bedrock (SigV4 covers the body) and Vertex are not routed. Refuse them in the caller.
+- A non-loopback `host` requires a token.
+- `OPTIONS` is refused: 401 without a token, 405 with one.
+
+Error bodies have the form `{ "error": { "type": "...", "message": "..." } }`.
+
+## Configuration
+
+```yaml
+# .skaile/transform-proxy.yaml
+transforms:
+  anon:
+    module: "@skaile/forge-anon/proxy"
+    config: { config: anon.config.yaml }
+pipelines:
+  anon: [anon]
+defaultPipeline: anon
+allowUpstreams:            # optional; default: any https origin, plus loopback http
+  - https://api.anthropic.com
+```
+
+Keys are exactly the option fields. An unknown top-level key is an error. Module specifiers resolve against the config file's directory.
+
+## CLI
+
+```sh
+skaile-transform-proxy [--config <file>] [--port <n>] [--host <h>] [--token <t>]
+```
+
+- The token comes from `--token` or `SKAILE_TRANSFORM_PROXY_TOKEN`.
+- Without `--config`, the proxy reads `./.skaile/transform-proxy.yaml`, then `~/.config/skaile/transform-proxy.yaml`.
+- On start it prints `listening <url>`. It stops on SIGINT or SIGTERM.
+
+## Library
+
+```ts
+import { createTransformProxy } from '@skaile/transform-proxy'
+
+const proxy = await createTransformProxy({
+  baseDir: process.cwd(),
+  transforms: { anon: { module: '@skaile/forge-anon/proxy', config: { config: 'anon.config.yaml' } } },
+  pipelines: { anon: ['anon'] },
+  defaultPipeline: 'anon',
+})
+proxy.session('s1').publisher('connector.patients').publish([{ kind: 'NAME_PATIENT', value: 'Alice' }])
+// ... clients use proxy.url with the headers above ...
+await proxy.dropSession('s1')
+await proxy.close()
+```
+
+## Writing a transform module
+
+A module default-exports a `TransformModule`:
+
+- `open(config, { baseDir, log })` runs once per proxy. It validates the config and builds shared state. Throwing rejects startup.
+- It returns a `TransformFactory`, which runs once per `(session, pipeline)`: `(ctx: { sessionId, facts, log }) => Transform`.
+- A `Transform` has `instruction?`, `outbound(text, leaf)`, `inbound(text)`, `inboundStream()` and `dispose?()`.
+
+`inboundStream().push(c1) + … + flush()` must equal `inbound(c1 + … + cn)` for every chunking.
+
+Connectors publish facts through `proxy.session(id).publisher(source)`. Facts are in-process only.
+
+## Security notes
+
+- The default host is `127.0.0.1`. Set a token before binding elsewhere.
+- Use `allowUpstreams` to limit where requests can go.
+- Clear text never leaves the proxy in a transformed field. Auth headers are relayed, not logged.
+- Mappings, facts and the signature cache are kept in memory and are lost on restart.

package/dist/cli.d.mts

@@ -0,0 +1,17 @@
+import { i as TransformProxy } from "./server-D5nBnO7T.mjs";
+/** Environment variable that supplies the client token when `--token` is absent. */
+export declare const TOKEN_ENV = "SKAILE_TRANSFORM_PROXY_TOKEN";
+export interface CliEnvironment {
+  readonly cwd: string;
+  readonly home: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly stdout: (line: string) => void;
+  readonly stderr: (line: string) => void;
+}
+/** `proxy` is set only when the server started; the caller owns its shutdown. */
+export interface CliRun {
+  readonly code: number;
+  readonly proxy?: TransformProxy;
+}
+/** Parses the arguments, loads the config and starts the proxy. Never installs signal handlers. */
+export declare function runCli(argv: readonly string[], io: CliEnvironment): Promise<CliRun>;

package/dist/cli.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { d as createTransformProxy, g as errorMessage, o as resolveProxyConfig } from "./config-BKD-ILIz.mjs";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { parseArgs } from "node:util";
+// src/cli.ts
+/** Environment variable that supplies the client token when `--token` is absent. */
+const TOKEN_ENV = "SKAILE_TRANSFORM_PROXY_TOKEN";
+const USAGE = "usage: skaile-transform-proxy [--config <file>] [--port <n>] [--host <h>] [--token <t>]";
+/** Parses the arguments, loads the config and starts the proxy. Never installs signal handlers. */
+async function runCli(argv, io) {
+	let values;
+	try {
+		({values} = parseArgs({
+			args: [...argv],
+			allowPositionals: false,
+			options: {
+				config: { type: "string" },
+				port: { type: "string" },
+				host: { type: "string" },
+				token: { type: "string" },
+				help: {
+					type: "boolean",
+					short: "h"
+				}
+			}
+		}));
+	} catch (err) {
+		io.stderr(errorMessage(err));
+		io.stderr(USAGE);
+		return { code: 2 };
+	}
+	if (values.help === true) {
+		io.stdout(USAGE);
+		return { code: 0 };
+	}
+	const port = parsePort(values.port);
+	if (port === void 0 && values.port !== void 0) {
+		io.stderr(`--port must be an integer from 0 to 65535, got "${values.port}"`);
+		return { code: 2 };
+	}
+	let config;
+	try {
+		config = resolveProxyConfig({
+			explicit: values.config,
+			cwd: io.cwd,
+			home: io.home
+		});
+	} catch (err) {
+		io.stderr(errorMessage(err));
+		return { code: 1 };
+	}
+	try {
+		const proxy = await createTransformProxy({
+			...config.options,
+			host: values.host,
+			port,
+			token: values.token ?? io.env["SKAILE_TRANSFORM_PROXY_TOKEN"],
+			log: {
+				debug: () => {},
+				info: () => {},
+				warn: (msg, ...args) => io.stderr(format("warn", msg, args)),
+				error: (msg, ...args) => io.stderr(format("error", msg, args))
+			}
+		});
+		io.stdout(`listening ${proxy.url}`);
+		return {
+			code: 0,
+			proxy
+		};
+	} catch (err) {
+		io.stderr(errorMessage(err));
+		return { code: 1 };
+	}
+}
+function parsePort(value) {
+	if (value === void 0 || !/^\d+$/.test(value)) return void 0;
+	const port = Number(value);
+	return port <= 65535 ? port : void 0;
+}
+function format(level, msg, args) {
+	return [`[transform-proxy ${level}] ${msg}`, ...args.map(String)].join(" ");
+}
+/** True when this module is the executed entry point (the bin, or `bun src/cli.ts`). */
+function isEntryPoint() {
+	const entry = process.argv[1];
+	if (entry === void 0) return false;
+	try {
+		return realpathSync(entry) === fileURLToPath(import.meta.url);
+	} catch {
+		return false;
+	}
+}
+if (isEntryPoint()) {
+	const run = await runCli(process.argv.slice(2), {
+		cwd: process.cwd(),
+		home: homedir(),
+		env: process.env,
+		stdout: (line) => console.log(line),
+		stderr: (line) => console.error(line)
+	});
+	if (run.proxy === void 0) process.exitCode = run.code;
+	else {
+		const proxy = run.proxy;
+		const stop = () => {
+			proxy.close().then(() => process.exit(0), (err) => {
+				console.error(errorMessage(err));
+				process.exit(1);
+			});
+		};
+		process.once("SIGINT", stop);
+		process.once("SIGTERM", stop);
+	}
+}
+export { TOKEN_ENV, runCli };