@amalgm/core 0.1.0

package/dist/transport/ingress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingress.d.ts","sourceRoot":"","sources":["../../src/transport/ingress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAM7C,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,QAAkB,CAAC;AAEpD,8HAA8H;AAC9H,eAAO,MAAM,yBAAyB;;;CAG5B,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAkBpC,CAAC;AAEZ;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS7F;AAED,+GAA+G;AAC/G,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAElE;AAMD,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED,0HAA0H;AAC1H,eAAO,MAAM,sBAAsB,4EAIzB,CAAC;AAEX,qGAAqG;AACrG,eAAO,MAAM,aAAa,4EAIhB,CAAC;AAEX,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,kBAAkB,GAAG,IAAI,CAiBhF;AAED,uGAAuG;AACvG,MAAM,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;AAEzF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW,EACpB,SAAS,SAAW,GACnB,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAM5G;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,mOAYtB,CAAC;AAEX,kFAAkF;AAClF,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOtF"}

package/dist/transport/ingress.js

@@ -0,0 +1,171 @@
+/**
+ * Event-rail ingress — the pipe half of the webhook rail. Success at
+ * this layer means exactly one thing: the immutable envelope (raw
+ * body + allowlisted headers) is durably queued and acknowledged.
+ * What a delivery TRIGGERS — the automation fan-out below
+ * events/processor.js:119 — is product logic and deliberately not
+ * here: the pipe stores and acknowledges the mail, it never reads it
+ * (axiom 3). The signature laws live at this layer because verifying
+ * WHO sent a payload is admission, not interpretation.
+ *
+ * Ported from amalgm-mcp/events/ingress.js (receipt contract) and
+ * events/matcher.js (signature laws — already pure in the engine).
+ */
+// ---------------------------------------------------------------------------
+// Receipt contract — events/ingress.js
+// ---------------------------------------------------------------------------
+/** ingress.js:12 — the body cap. Counted over raw bytes as they stream in, not after assembly. */
+export const MAX_EVENT_BODY_BYTES = 2 * 1024 * 1024;
+/** The over-limit rejection — ingress.js:50-53 surfaced through the generic error path (:80): status + byte-exact message. */
+export const EVENT_BODY_LIMIT_EXCEEDED = {
+    status: 413,
+    message: `Event body exceeds ${MAX_EVENT_BODY_BYTES} bytes`,
+};
+/**
+ * The 17-header storage allowlist — ingress.js:13-31. Everything else
+ * is dropped BEFORE the envelope is persisted: the envelope is
+ * immutable and replayed, so an unlisted header stored today is a
+ * secret leaked forever. The list is exactly: routing identity
+ * (x-amalgm-*), each supported sender's event/delivery markers, and
+ * every signature/secret header the matcher may need to re-verify.
+ */
+export const STORED_HEADERS = new Set([
+    'authorization',
+    'content-type',
+    'stripe-signature',
+    'x-amalgm-delivery-id',
+    'x-amalgm-event',
+    'x-amalgm-source',
+    'x-amalgm-webhook-secret',
+    'x-github-delivery',
+    'x-github-event',
+    'x-gitlab-event',
+    'x-gitlab-token',
+    'x-hub-signature',
+    'x-hub-signature-256',
+    'x-linear-event',
+    'x-linear-signature',
+    'x-webhook-secret',
+    'x-webhook-signature',
+]);
+/**
+ * ingress.js:33-42 — filter to the allowlist, lowercase the names,
+ * join repeated values with ', ', stringify the rest. The result is
+ * the envelope's header record — and the flattened shape every
+ * signature function below reads.
+ */
+export function storedHeaders(headers) {
+    const result = {};
+    for (const [key, value] of Object.entries(headers || {})) {
+        const normalized = key.toLowerCase();
+        if (!STORED_HEADERS.has(normalized))
+            continue;
+        if (Array.isArray(value))
+            result[normalized] = value.join(', ');
+        else if (value != null)
+            result[normalized] = String(value);
+    }
+    return result;
+}
+/** The receipt acknowledgment — ingress.js:73-78: 202, because acceptance is durable-queued, not processed. */
+export const EVENT_ACCEPTED_STATUS = 202;
+export function eventAcceptedBody(deliveryId, status) {
+    return { ok: true, accepted: true, deliveryId, status };
+}
+/** matcher.js:13-17 — HMAC proof headers, in precedence order (generic first, then GitHub's sha256, then legacy sha1). */
+export const HMAC_SIGNATURE_HEADERS = [
+    'x-webhook-signature',
+    'x-hub-signature-256',
+    'x-hub-signature',
+];
+/** matcher.js:19-23 — plain shared-secret headers, in precedence order (ours, generic, GitLab's). */
+export const TOKEN_HEADERS = [
+    'x-amalgm-webhook-secret',
+    'x-webhook-secret',
+    'x-gitlab-token',
+];
+/**
+ * The extraction order — matcher.js:28-43: every HMAC header first
+ * (an HMAC proof is stronger than a bearer secret, so it must win
+ * when a sender supplies both), then `Authorization: Bearer <secret>`
+ * (reported under header 'authorization'), then the plain token
+ * headers. First PRESENT header wins — an empty value reads as
+ * absent. Null when nothing proves anything.
+ */
+export function extractSignature(headers) {
+    for (const header of HMAC_SIGNATURE_HEADERS) {
+        const value = headers[header];
+        if (value)
+            return { header, value };
+    }
+    const authorization = headers['authorization'];
+    if (typeof authorization === 'string') {
+        const match = authorization.match(/^Bearer\s+(.+)$/i);
+        if (match)
+            return { header: 'authorization', value: match[1] ?? '' };
+    }
+    for (const header of TOKEN_HEADERS) {
+        const value = headers[header];
+        if (value)
+            return { header, value };
+    }
+    return null;
+}
+/**
+ * matcher.js:48-50 — the expected proof is `<algorithm>=<hex>`,
+ * sha256 unless the caller says otherwise (verification picks sha1
+ * only when the presented value announces it — GitHub's legacy
+ * x-hub-signature).
+ */
+export function computeSignature(secret, rawBody, hmacHex, algorithm = 'sha256') {
+    return `${algorithm}=` + hmacHex(algorithm, secret, rawBody);
+}
+/**
+ * matcher.js:122-128 — the human-readable source label, first
+ * recognized marker wins in this order: github → stripe → linear →
+ * gitlab → 'external'.
+ */
+export function pickSourceLabel(headers) {
+    if (headers['x-github-event'])
+        return 'github';
+    if (headers['stripe-signature'])
+        return 'stripe';
+    if (headers['x-linear-event'])
+        return 'linear';
+    if (headers['x-gitlab-event'])
+        return 'gitlab';
+    return 'external';
+}
+/**
+ * The 11 headers worth handing to the agent run context —
+ * matcher.js:133-145. Note the deliberate asymmetry with
+ * STORED_HEADERS: secrets used only for admission (authorization,
+ * x-amalgm-webhook-secret, x-webhook-secret) are stored for
+ * re-verification but NOT passed through to agent context — except
+ * x-gitlab-token, which GitLab overloads as both auth and event
+ * metadata.
+ */
+export const PASSTHROUGH_HEADERS = [
+    'x-github-event',
+    'x-github-delivery',
+    'x-hub-signature-256',
+    'x-hub-signature',
+    'stripe-signature',
+    'x-webhook-signature',
+    'content-type',
+    'x-linear-event',
+    'x-linear-signature',
+    'x-gitlab-event',
+    'x-gitlab-token',
+];
+/** matcher.js:147-151 — project the passthrough subset, preserving list order. */
+export function collectPassthroughHeaders(headers) {
+    const out = {};
+    for (const header of PASSTHROUGH_HEADERS) {
+        const value = headers[header];
+        if (value)
+            out[header] = value;
+    }
+    return out;
+}
+//# sourceMappingURL=ingress.js.map

package/dist/transport/ingress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingress.js","sourceRoot":"","sources":["../../src/transport/ingress.ts"],"names":[],"mappings":"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"}

package/dist/transport/routing.d.ts

@@ -0,0 +1,235 @@
+/**
+ * ONE routing table (axiom 4). The engine carries three drifted copies
+ * of these laws — local-gateway.js:133-176,627-654 (the gateway's own
+ * dispatch), tunnel-events.js:58-89,279-353 and tunnel-chat.js:33-64,
+ * 138-194,286-300 (each tunnel's local delivery) — and every incident
+ * where a new REST prefix worked over the tunnel but 404'd locally (or
+ * vice versa) is that drift cashing out. This module is the one
+ * definition; the table CONTENTS are injected product configuration
+ * (the kernel routes, it does not know what chat is — axiom 3), with
+ * the engine's shipped lists exported from shipped-routes.ts.
+ *
+ * The pipe never reads the mail: everything here classifies pathnames
+ * and port numbers. Nothing inspects a payload.
+ */
+/** The four services a runtime pathname can resolve to. */
+export type RuntimeService = 'gateway' | 'portMonitor' | 'chat' | 'mcp';
+/**
+ * The declared-port probe order — tunnel-events.js:315, byte-order
+ * preserved (mcp before chat; the sets never overlap in practice, but
+ * order is contract until proven dead).
+ */
+export declare const RUNTIME_SERVICES: readonly ["gateway", "portMonitor", "mcp", "chat"];
+/**
+ * The one routing table. Buckets are prefix lists; gateway
+ * additionally owns a set of exact paths. Contents are product
+ * configuration — see shippedRouteTable for the engine's lists.
+ */
+export interface RouteTable {
+    readonly gatewayPrefixes: readonly string[];
+    readonly gatewayExactPaths: readonly string[];
+    readonly portMonitorPrefixes: readonly string[];
+    readonly chatPrefixes: readonly string[];
+    readonly mcpPrefixes: readonly string[];
+}
+/**
+ * The prefix law — tunnel-events.js:279-281, identical in chat and
+ * gateway: a prefix claims itself and everything below a '/'
+ * boundary. '/chat' claims '/chat' and '/chat/x', never
+ * '/chat-payloads' — segment-honest matching is what lets '/chat' and
+ * '/chat-payloads' live in different buckets.
+ */
+export declare function prefixMatches(pathname: string, prefix: string): boolean;
+/**
+ * tunnel-events.js:283-289 (framePathname) / runtime-auth.js:102-108
+ * (pathnameFor) — one copy. Tunnel frame paths and req.url both carry
+ * query strings; routing decisions are over the pathname alone.
+ * Unparseable input routes as '/'.
+ */
+export declare function pathnameOf(path: string | null | undefined): string;
+/**
+ * The classifier — canonical order is the TUNNEL order
+ * (tunnel-events.js:291-300): gateway (exact paths first, then
+ * prefixes) → portMonitor → chat → mcp → null.
+ *
+ * The engine's gateway checks chat → mcp → portMonitor instead
+ * (local-gateway.js:627-647, after handling its own routes). The two
+ * orders are currently indistinguishable because no prefix in one
+ * bucket sits under a prefix in another — no pathname can match two
+ * buckets, so match order never decides a winner. That is an
+ * assumption about table CONTENTS, so assertNoBucketCollisions below
+ * makes it executable: run it over any injected table and the
+ * "order doesn't matter" claim is proven, not remembered.
+ */
+export declare function serviceForRuntimePath(pathname: string, table: RouteTable): RuntimeService | null;
+/**
+ * The executable form of the order-indistinguishability assumption:
+ * two prefixes from different buckets may never claim the same
+ * pathname. Prefix a and prefix b share a claimable pathname exactly
+ * when one prefix-matches the other (then the deeper prefix itself is
+ * such a pathname), so that is the whole check. Gateway exact paths
+ * are also checked against the other buckets' prefixes: both shipped
+ * orders test gateway first, and this keeps even that ordering
+ * non-load-bearing.
+ */
+export declare function assertNoBucketCollisions(table: RouteTable): void;
+/**
+ * The gateway's prefix-strip law — local-gateway.js:637-645: before
+ * proxying to the port monitor it strips '/port-monitor', else
+ * '/ports' (first match wins, checked in this order), but deliberately
+ * NOT '/api/ports' — that one is the port monitor's own native prefix
+ * and forwards verbatim. '/chat' and '/mcp'-bucket paths always
+ * forward verbatim (stripPrefix '').
+ */
+export declare const PORT_MONITOR_STRIP_PREFIXES: readonly ["/port-monitor", "/ports"];
+export interface ForwardTarget {
+    readonly service: RuntimeService;
+    readonly forwardPath: string;
+}
+/**
+ * Classify a pathname and compute the path to forward upstream —
+ * local-gateway.js:627-647 (serviceForPath) + :687-692 (proxiedPath,
+ * slice then `|| '/'`), generalized over the injected table. Pathname
+ * in, pathname out: the host re-attaches the query string, as
+ * proxiedPath does.
+ *
+ * DRIFT, documented as a wound the cutover closes: the tunnels
+ * forward frame paths VERBATIM to the resolved service
+ * (tunnel-events.js:678-684 passes frame.path straight to
+ * http.request), so '/ports/x' reaches the port monitor as '/ports/x'
+ * over a tunnel but as '/x' through the gateway. The gateway behavior
+ * ported here is canonical; when the tunnels adopt this function the
+ * two paths converge.
+ *
+ * Two deliberate departures from the engine's serviceForPath, both
+ * because this is the whole table rather than the gateway's slice of
+ * it: gateway-bucket paths return {service:'gateway'} instead of null
+ * (the engine returns null there because the gateway has already
+ * handled its own routes by that line), and the strip test uses the
+ * classified pathname, where the engine's raw startsWith is
+ * indistinguishable ('/portsfoo' never classifies as portMonitor).
+ */
+export declare function forwardPathForService(pathname: string, table: RouteTable): ForwardTarget | null;
+/** tunnel-events.js:274-277 — a port is an integer in (0, 65535], or it is nothing. */
+export declare function validPort(value: unknown): number | null;
+/** A fully resolved port per service (defaults come from the host's runtime manifest). */
+export interface RuntimePorts {
+    readonly gateway: number;
+    readonly portMonitor: number;
+    readonly mcp: number;
+    readonly chat: number;
+}
+/** Possibly-partial ports as read from a runtime-state file of unknown age. */
+export type RuntimePortsLike = {
+    readonly [service in RuntimeService]?: number | null | undefined;
+};
+/** The subset of runtime-state.json the port mapping reads. */
+export interface RuntimeStateLike {
+    readonly gateway_port?: unknown;
+    readonly ports?: {
+        readonly gateway?: unknown;
+        readonly port_monitor?: unknown;
+        readonly amalgm_mcp?: unknown;
+        readonly chat_server?: unknown;
+    } | null;
+}
+/**
+ * The runtime-state port mapping — the tunnels' `readRuntimePorts`
+ * (tunnel-events.js:255-272, byte-identical in tunnel-chat.js:114-131;
+ * the engine name is kept — the manifest's declaration-driven
+ * `runtimePortsFromState` is a different law and lives in
+ * `supervision/service-registration.ts`). Top-level `gateway_port` wins
+ * over `ports.gateway` (older writers only wrote the former); the
+ * other services live only under `ports.*` in snake_case. `Number(x)
+ * || fallback` verbatim: absent, unparseable, and zero all fall back.
+ * The engine's catch-branch (unreadable file) is the host's: pass no
+ * state and the fallbacks come through whole.
+ */
+export declare function readRuntimePorts(state: RuntimeStateLike | null | undefined, fallbacks: RuntimePorts): RuntimePorts;
+/**
+ * The mirror-write shape — local-gateway.js:395-402: what the gateway
+ * writes is exactly what readRuntimePorts reads, top-level
+ * `gateway_port` doubled into `ports.gateway` included.
+ */
+export declare function runtimeStatePortsPatch(ports: RuntimePorts): {
+    gateway_port: number;
+    ports: {
+        gateway: number;
+        port_monitor: number;
+        amalgm_mcp: number;
+        chat_server: number;
+    };
+};
+/** tunnel-events.js:302-308 — which service does a well-known DEFAULT port imply? Checked against defaults, never live ports. */
+export declare function defaultServiceForPort(port: number, defaults: RuntimePorts): RuntimeService | null;
+/** tunnel-events.js:310-312 — live port if valid, else the default; null when both are broken. */
+export declare function runtimePortForService(runtimePorts: RuntimePortsLike, defaults: RuntimePorts, service: RuntimeService): number | null;
+/** tunnel-events.js:314-316 — is this port one the live runtime actually declared? Order-sensitive over RUNTIME_SERVICES. */
+export declare function isDeclaredRuntimePort(port: number, runtimePorts: RuntimePortsLike): boolean;
+/**
+ * The full set of ports a tunnel frame may target —
+ * tunnel-events.js:318-326: every resolvable service port plus, on
+ * the events tunnel, every advertised app-route port. DRIFT:
+ * tunnel-chat.js:177-184 omits the app ports (chat frames never
+ * target apps); that divergence is this parameter, not a second copy
+ * — pass no appRoutePorts and you have the chat version.
+ */
+export declare function allowedTargetPorts(runtimePorts: RuntimePortsLike, defaults: RuntimePorts, appRoutePorts?: Iterable<number>): Set<number>;
+/** The wire fields target resolution reads, named as the tunnel frame names them. */
+export interface TunnelFrameTarget {
+    readonly target_port?: unknown;
+    readonly path?: string | null;
+}
+export interface ResolveTargetPortOptions {
+    readonly runtimePorts: RuntimePortsLike;
+    readonly defaults: RuntimePorts;
+    readonly table: RouteTable;
+    /**
+     * 'mcp' for the events tunnel, 'chat' for the chat tunnel. The
+     * events engine derives this as `fallbackPort === defaultTargetPort()
+     * ? 'mcp' : defaultServiceForPort(fallbackPort)` (tunnel-events.js:343)
+     * — but no caller ever passes a fallbackPort, so the derivation is
+     * always 'mcp'; the chat tunnel hardcodes 'chat'
+     * (tunnel-chat.js:291). Injected here instead of re-porting a dead
+     * parameter.
+     */
+    readonly fallbackService: RuntimeService;
+    /** App-route ports (events tunnel only) — see allowedTargetPorts. */
+    readonly appRoutePorts?: Iterable<number>;
+}
+/**
+ * The target-port law — canonical form is tunnel-events.js:338-353
+ * (tunnel-chat.js:286-300 is the same law with fallbackService
+ * 'chat' and no app ports):
+ *  1. a requested port the live runtime declared is honored verbatim;
+ *  2. otherwise the frame's PATH picks the service — but only when no
+ *     port was requested, or the requested port is a well-known
+ *     default (a stale peer aiming at where a service used to live:
+ *     the path outranks the stale number and both remap to the live
+ *     port);
+ *  3. a requested port that names neither a declared port, a default,
+ *     nor a routable path must be in the allowed set (app routes) or
+ *     it resolves to null — and null is the denial contract below.
+ */
+export declare function resolveTargetPort(frame: TunnelFrameTarget, options: ResolveTargetPortOptions): number | null;
+/** Tunnel res-frame denial — tunnel-events.js:668-674 (and stream/ws variants at :710-715,:778-779). */
+export declare const TARGET_PORT_DENIED_STATUS = 403;
+export declare const TARGET_PORT_DENIED_MESSAGE = "Target port is not allowed";
+/** The frozen body bytes of the non-stream denial (JSON.stringify({ error: ... }) at :673). */
+export declare const TARGET_PORT_DENIED_BODY = "{\"error\":\"Target port is not allowed\"}";
+/** WebSocket denial — tunnel-events.js:779: policy-violation close with the same reason. */
+export declare const WS_CLOSE_TARGET_PORT_DENIED: {
+    readonly code: 1008;
+    readonly reason: "Target port is not allowed";
+};
+/** Gateway preview denial — local-gateway.js:675. */
+export declare function previewPortDeniedError(port: number): {
+    status: 403;
+    message: string;
+};
+/** Gateway app denial — local-gateway.js:662. */
+export declare function appNotRoutableError(appRef: string): {
+    status: 404;
+    message: string;
+};
+//# sourceMappingURL=routing.d.ts.map

package/dist/transport/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/transport/routing.ts"],"names":[],"mappings":"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"}