@amalgm/core 0.1.0

package/dist/transport/auth.d.ts

@@ -0,0 +1,232 @@
+/**
+ * The runtime auth boundary — every HTTP request and WebSocket upgrade
+ * that reaches a runtime service passes this gate first. Ported from
+ * the engine's runtime/scripts/runtime-auth.js, whose 162 lines are
+ * pure decision logic wearing Node clothing: the env read, the crypto
+ * compare, and the res writes are the host's; only the verdicts live
+ * here (axiom 6). Contracts — header names, the Bearer regex, the 401
+ * body, close codes — are byte-exact (axiom 8).
+ *
+ * The trust model in one line: possession of the runtime token IS
+ * authorization, and the token never leaves the machine except inside
+ * a tunnel frame the runtime itself stamped.
+ */
+/**
+ * THE copy of the runtime token header name. The engine spells this
+ * string in four places (runtime-auth.js:5, local-gateway.js:72, and
+ * inline in both tunnels' localHeaders); cutover deletes the other
+ * three.
+ */
+export declare const RUNTIME_TOKEN_HEADER = "x-amalgm-runtime-token";
+/** An env-shaped bag of strings. The host passes process.env; tests pass literals. */
+export interface EnvLike {
+    readonly [name: string]: string | undefined;
+}
+/**
+ * Header maps as Node hands them over: lowercased names, values that
+ * may be strings, repeated-header arrays, or (after a JSON round trip
+ * through a tunnel frame) numbers.
+ */
+export type HeaderValue = string | number | readonly string[] | null | undefined;
+export interface HeadersLike {
+    readonly [name: string]: HeaderValue;
+}
+/** runtime-auth.js:26-30 — first value wins for repeated headers; non-strings read as absent. */
+export declare function headerValue(headers: HeadersLike | null | undefined, name: string): string;
+/** runtime-auth.js:7-9 — the expected token is the env token, trimmed. Empty means "none configured". */
+export declare function runtimeTokenFromEnv(env: EnvLike): string;
+/**
+ * runtime-auth.js:11-18 — when is the gate armed? The explicit
+ * disable wins first, always; otherwise any of: a configured token,
+ * an npm-sourced runtime, or local mode. The npm/local clauses arm
+ * the gate even with no token configured — which the verdict law
+ * below turns into deny-everything, deliberately: a runtime that
+ * should have a token but lost it must fail closed, not open.
+ */
+export declare function runtimeAuthRequired(env: EnvLike): boolean;
+/** The one Bearer shape the boundary accepts — runtime-auth.js:47. */
+export declare const BEARER_TOKEN_PATTERN: RegExp;
+/**
+ * Browser WebSocket clients cannot set headers, so the token rides the
+ * subprotocol list as `amalgm-runtime-token.<token>` — runtime-auth.js:32-40.
+ */
+export declare const RUNTIME_TOKEN_PROTOCOL_PREFIX = "amalgm-runtime-token.";
+export declare function tokenFromProtocol(headers: HeadersLike): string;
+/**
+ * Token extraction precedence — runtime-auth.js:42-54, in order:
+ *  1. the dedicated header,
+ *  2. `Authorization: Bearer <token>` (trimmed),
+ *  3. the WebSocket subprotocol entry,
+ *  4. nothing.
+ * First non-empty wins; a present-but-empty earlier source falls
+ * through rather than shadowing a later one.
+ */
+export declare function tokenFromHeaders(headers: HeadersLike): string;
+/**
+ * The constant-time byte compare is a host effect: node:crypto's
+ * timingSafeEqual, or the WebCrypto equivalent. Called only with
+ * equal-length inputs — the length gate lives in safeTokenEqual.
+ */
+export type TimingSafeEqualPort = (left: Uint8Array, right: Uint8Array) => boolean;
+/**
+ * runtime-auth.js:20-24 — UTF-8 encode both sides, length check
+ * first (node's timingSafeEqual throws on mismatched lengths; the
+ * early return also leaks nothing an attacker doesn't already know,
+ * since token length is not secret), then the injected constant-time
+ * compare.
+ */
+export declare function safeTokenEqual(actual: unknown, expected: unknown, timingSafeEqual: TimingSafeEqualPort): boolean;
+/** The three facts the verdict needs, resolved once by the host from env + adapters. */
+export interface RuntimeAuthPolicy {
+    /** runtimeAuthRequired(env) — is the gate armed at all? */
+    readonly required: boolean;
+    /** runtimeTokenFromEnv(env) — '' means "armed but no token", which denies everything. */
+    readonly expectedToken: string;
+    readonly timingSafeEqual: TimingSafeEqualPort;
+}
+/**
+ * The verdict law — runtime-auth.js:56-61:
+ *  - gate not armed → allow, unconditionally;
+ *  - gate armed with no expected token → DENY, unconditionally
+ *    (fail closed — see runtimeAuthRequired);
+ *  - otherwise, constant-time compare of presented vs expected.
+ */
+export declare function isAuthorizedRuntimeRequest(headers: HeadersLike, policy: RuntimeAuthPolicy): boolean;
+/** The only hosts a browser origin may claim and still be "this machine" — runtime-auth.js:69. */
+export declare const LOOPBACK_ORIGIN_HOSTNAMES: string[];
+/**
+ * runtime-auth.js:63-74. An EMPTY origin returns TRUE, deliberately:
+ * no Origin header means no foreign web page — curl, native fetch,
+ * Electron's main process, and same-origin requests all omit it, and
+ * CORS is enforced by browsers alone, so a client that sends no
+ * Origin ignores these headers anyway. The gate exists to stop a
+ * hostile *page* on another origin from riding a user's browser into
+ * the runtime; absence of an origin is absence of that threat. An
+ * unparseable origin, by contrast, is a claim we cannot verify: false.
+ * ('::1' is unreachable through WHATWG parsing, which brackets IPv6
+ * hostnames — kept verbatim from the engine per axiom 8.)
+ */
+export declare function isLoopbackOrigin(origin: string | null | undefined): boolean;
+/** CORS contract defaults — runtime-auth.js:83-96, byte-exact including order. */
+export declare const RUNTIME_CORS_METHODS = "GET, POST, DELETE, OPTIONS";
+export declare const RUNTIME_CORS_ALLOWED_HEADERS: string;
+export interface RuntimeCorsOptions {
+    readonly methods?: string;
+    readonly headers?: string;
+    readonly exposeHeaders?: string;
+}
+/**
+ * runtime-auth.js:76-100 as a header map instead of res.setHeader
+ * calls (insertion order preserved). Allow-Origin echoes the origin
+ * only when it is a loopback page — plus Vary so caches never serve
+ * one origin's grant to another. Methods and allowed headers are set
+ * unconditionally.
+ */
+export declare function runtimeCorsHeaders(origin: string, options?: RuntimeCorsOptions): Record<string, string>;
+/**
+ * The rejection contract — runtime-auth.js:115-121, byte-exact. The
+ * body is the frozen serialization, not a fresh stringify: parity
+ * tests pin the bytes, not the shape.
+ */
+export declare const UNAUTHORIZED_RESPONSE: {
+    readonly status: 401;
+    readonly headers: {
+        readonly 'Content-Type': "application/json";
+        readonly 'Cache-Control': "no-store";
+    };
+    readonly body: "{\"error\":\"Missing or invalid Amalgm runtime token\"}";
+};
+/** runtime-auth.js:110-113 — health probes answer before auth, always. Pure over an already-parsed pathname. */
+export declare function isHealthPath(pathname: string): boolean;
+/** runtime-auth.js:138 — health paths plus caller-declared prefix exemptions (plain startsWith, not segment-aware). */
+export declare function isExemptPath(pathname: string, exemptPrefixes?: readonly string[]): boolean;
+export interface RuntimeHttpRequest {
+    readonly method: string;
+    /** Already parsed from req.url — see pathnameOf in routing.ts. */
+    readonly pathname: string;
+    readonly headers: HeadersLike;
+}
+export interface RuntimeHttpOptions {
+    readonly exemptPrefixes?: readonly string[];
+}
+export type RuntimeHttpDecision = {
+    readonly kind: 'preflight';
+    readonly status: 204 | 403;
+} | {
+    readonly kind: 'allow';
+} | {
+    readonly kind: 'reject';
+    readonly status: 401;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+};
+/**
+ * The decision skeleton of authorizeRuntimeHttp — runtime-auth.js:123-143
+ * minus the side effects (the host applies runtimeCorsHeaders to every
+ * response and writes whichever verdict comes back):
+ *  - OPTIONS is the preflight law (:126-134): 204 for loopback or
+ *    absent origins, 403 for everyone else — preflights are never
+ *    token-checked, because browsers refuse to attach credentials to
+ *    them;
+ *  - exempt paths and authorized requests pass;
+ *  - everything else gets the byte-exact 401.
+ */
+export declare function decideRuntimeHttp(request: RuntimeHttpRequest, policy: RuntimeAuthPolicy, options?: RuntimeHttpOptions): RuntimeHttpDecision;
+/** The three facts the bearer guard needs: the request's headers, the
+ * token the product expects, and the injected constant-time compare. */
+export interface BearerGuardInput {
+    readonly headers: HeadersLike;
+    readonly expectedToken: string;
+    readonly timingSafeEqual: TimingSafeEqualPort;
+}
+export type BearerGuardVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly status: 401;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+};
+/**
+ * The composed bearer guard a product calls at its HTTP boundary —
+ * hoisted from the four bricks (apps, tools, agents, browser) that each
+ * hand-rolled it, with drift including a non-timing-safe compare and a
+ * case-sensitive Bearer parse. This is those four guards as ONE law,
+ * assembled entirely from the primitives above (zero duplicated logic):
+ *
+ *  - the token arrives by {@link tokenFromHeaders} — the dedicated
+ *    header, `Authorization: Bearer` (case-insensitive scheme), or the
+ *    WS subprotocol carrier, in that precedence;
+ *  - the compare is {@link safeTokenEqual} over the injected
+ *    constant-time port (axiom 6);
+ *  - every failure — token missing, token wrong, no expected token
+ *    configured (fail closed, as the verdict law) — is the SAME
+ *    byte-exact {@link UNAUTHORIZED_RESPONSE}, so a caller never learns
+ *    which check refused it.
+ */
+export declare function guardBearerRequest(input: BearerGuardInput): BearerGuardVerdict;
+/**
+ * runtime-auth.js:145-152 — outbound stamping: attach the runtime
+ * token to a header bag, or return the bag untouched when there is no
+ * token to attach (never an empty header).
+ */
+export declare function withRuntimeToken(headers: Record<string, string>, token: string): Record<string, string>;
+/**
+ * WebSocket close codes the gateway speaks — local-gateway.js:866,873,
+ * 1061,1074 and the tunnels' denial path. 4401/4404 are the private-use
+ * mirrors of 401/404 (the WS close-code space reserves 4000-4999 for
+ * applications); 1008 is the RFC 6455 policy-violation code, used for
+ * target-port denial and unknown routes; 1011 is unexpected-condition,
+ * used when the upstream leg fails (reason = the upstream error message).
+ */
+export declare const WS_CLOSE_UNAUTHORIZED: {
+    readonly code: 4401;
+    readonly reason: "Unauthorized";
+};
+export declare const WS_CLOSE_PTY_SESSION_NOT_FOUND: {
+    readonly code: 4404;
+    readonly reason: "PTY session not found";
+};
+export declare const WS_CLOSE_POLICY_VIOLATION = 1008;
+export declare const WS_CLOSE_UPSTREAM_FAILURE = 1011;
+//# sourceMappingURL=auth.d.ts.map

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

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

package/dist/transport/auth.js

@@ -0,0 +1,266 @@
+/**
+ * The runtime auth boundary — every HTTP request and WebSocket upgrade
+ * that reaches a runtime service passes this gate first. Ported from
+ * the engine's runtime/scripts/runtime-auth.js, whose 162 lines are
+ * pure decision logic wearing Node clothing: the env read, the crypto
+ * compare, and the res writes are the host's; only the verdicts live
+ * here (axiom 6). Contracts — header names, the Bearer regex, the 401
+ * body, close codes — are byte-exact (axiom 8).
+ *
+ * The trust model in one line: possession of the runtime token IS
+ * authorization, and the token never leaves the machine except inside
+ * a tunnel frame the runtime itself stamped.
+ */
+const utf8 = new TextEncoder();
+/**
+ * THE copy of the runtime token header name. The engine spells this
+ * string in four places (runtime-auth.js:5, local-gateway.js:72, and
+ * inline in both tunnels' localHeaders); cutover deletes the other
+ * three.
+ */
+export const RUNTIME_TOKEN_HEADER = 'x-amalgm-runtime-token';
+/** runtime-auth.js:26-30 — first value wins for repeated headers; non-strings read as absent. */
+export function headerValue(headers, name) {
+    const raw = headers?.[name.toLowerCase()];
+    if (Array.isArray(raw))
+        return raw[0] || '';
+    return typeof raw === 'string' ? raw : '';
+}
+/** runtime-auth.js:7-9 — the expected token is the env token, trimmed. Empty means "none configured". */
+export function runtimeTokenFromEnv(env) {
+    return String(env.AMALGM_RUNTIME_TOKEN || '').trim();
+}
+/**
+ * runtime-auth.js:11-18 — when is the gate armed? The explicit
+ * disable wins first, always; otherwise any of: a configured token,
+ * an npm-sourced runtime, or local mode. The npm/local clauses arm
+ * the gate even with no token configured — which the verdict law
+ * below turns into deny-everything, deliberately: a runtime that
+ * should have a token but lost it must fail closed, not open.
+ */
+export function runtimeAuthRequired(env) {
+    if (env.AMALGM_RUNTIME_AUTH === 'disabled')
+        return false;
+    return Boolean(runtimeTokenFromEnv(env)
+        || env.AMALGM_RUNTIME_SOURCE === 'npm'
+        || env.AMALGM_LOCAL_MODE === 'true');
+}
+/** The one Bearer shape the boundary accepts — runtime-auth.js:47. */
+export const BEARER_TOKEN_PATTERN = /^Bearer\s+(.+)$/i;
+/**
+ * Browser WebSocket clients cannot set headers, so the token rides the
+ * subprotocol list as `amalgm-runtime-token.<token>` — runtime-auth.js:32-40.
+ */
+export const RUNTIME_TOKEN_PROTOCOL_PREFIX = 'amalgm-runtime-token.';
+export function tokenFromProtocol(headers) {
+    const raw = headerValue(headers, 'sec-websocket-protocol');
+    for (const part of raw.split(',').map((value) => value.trim()).filter(Boolean)) {
+        if (part.startsWith(RUNTIME_TOKEN_PROTOCOL_PREFIX)) {
+            return part.slice(RUNTIME_TOKEN_PROTOCOL_PREFIX.length);
+        }
+    }
+    return '';
+}
+/**
+ * Token extraction precedence — runtime-auth.js:42-54, in order:
+ *  1. the dedicated header,
+ *  2. `Authorization: Bearer <token>` (trimmed),
+ *  3. the WebSocket subprotocol entry,
+ *  4. nothing.
+ * First non-empty wins; a present-but-empty earlier source falls
+ * through rather than shadowing a later one.
+ */
+export function tokenFromHeaders(headers) {
+    const headerToken = headerValue(headers, RUNTIME_TOKEN_HEADER);
+    if (headerToken)
+        return headerToken;
+    const match = headerValue(headers, 'authorization').match(BEARER_TOKEN_PATTERN);
+    if (match)
+        return (match[1] ?? '').trim();
+    const protocolToken = tokenFromProtocol(headers);
+    if (protocolToken)
+        return protocolToken;
+    return '';
+}
+/**
+ * runtime-auth.js:20-24 — UTF-8 encode both sides, length check
+ * first (node's timingSafeEqual throws on mismatched lengths; the
+ * early return also leaks nothing an attacker doesn't already know,
+ * since token length is not secret), then the injected constant-time
+ * compare.
+ */
+export function safeTokenEqual(actual, expected, timingSafeEqual) {
+    const left = utf8.encode(String(actual || ''));
+    const right = utf8.encode(String(expected || ''));
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/**
+ * The verdict law — runtime-auth.js:56-61:
+ *  - gate not armed → allow, unconditionally;
+ *  - gate armed with no expected token → DENY, unconditionally
+ *    (fail closed — see runtimeAuthRequired);
+ *  - otherwise, constant-time compare of presented vs expected.
+ */
+export function isAuthorizedRuntimeRequest(headers, policy) {
+    if (!policy.required)
+        return true;
+    if (!policy.expectedToken)
+        return false;
+    return safeTokenEqual(tokenFromHeaders(headers), policy.expectedToken, policy.timingSafeEqual);
+}
+/** The only hosts a browser origin may claim and still be "this machine" — runtime-auth.js:69. */
+export const LOOPBACK_ORIGIN_HOSTNAMES = ['localhost', '127.0.0.1', '[::1]', '::1'];
+/**
+ * runtime-auth.js:63-74. An EMPTY origin returns TRUE, deliberately:
+ * no Origin header means no foreign web page — curl, native fetch,
+ * Electron's main process, and same-origin requests all omit it, and
+ * CORS is enforced by browsers alone, so a client that sends no
+ * Origin ignores these headers anyway. The gate exists to stop a
+ * hostile *page* on another origin from riding a user's browser into
+ * the runtime; absence of an origin is absence of that threat. An
+ * unparseable origin, by contrast, is a claim we cannot verify: false.
+ * ('::1' is unreachable through WHATWG parsing, which brackets IPv6
+ * hostnames — kept verbatim from the engine per axiom 8.)
+ */
+export function isLoopbackOrigin(origin) {
+    if (!origin)
+        return true;
+    try {
+        const url = new URL(origin);
+        return ((url.protocol === 'http:' || url.protocol === 'https:')
+            && LOOPBACK_ORIGIN_HOSTNAMES.includes(url.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+/** CORS contract defaults — runtime-auth.js:83-96, byte-exact including order. */
+export const RUNTIME_CORS_METHODS = 'GET, POST, DELETE, OPTIONS';
+export const RUNTIME_CORS_ALLOWED_HEADERS = [
+    'Content-Type',
+    'Authorization',
+    'Accept',
+    'Cache-Control',
+    'Last-Event-ID',
+    'Mcp-Session-Id',
+    'X-Amalgm-Session-Id',
+    RUNTIME_TOKEN_HEADER,
+].join(', ');
+/**
+ * runtime-auth.js:76-100 as a header map instead of res.setHeader
+ * calls (insertion order preserved). Allow-Origin echoes the origin
+ * only when it is a loopback page — plus Vary so caches never serve
+ * one origin's grant to another. Methods and allowed headers are set
+ * unconditionally.
+ */
+export function runtimeCorsHeaders(origin, options = {}) {
+    const out = {};
+    if (origin && isLoopbackOrigin(origin)) {
+        out['Access-Control-Allow-Origin'] = origin;
+        out['Vary'] = 'Origin';
+    }
+    out['Access-Control-Allow-Methods'] = options.methods || RUNTIME_CORS_METHODS;
+    out['Access-Control-Allow-Headers'] = options.headers || RUNTIME_CORS_ALLOWED_HEADERS;
+    if (options.exposeHeaders)
+        out['Access-Control-Expose-Headers'] = options.exposeHeaders;
+    return out;
+}
+/**
+ * The rejection contract — runtime-auth.js:115-121, byte-exact. The
+ * body is the frozen serialization, not a fresh stringify: parity
+ * tests pin the bytes, not the shape.
+ */
+export const UNAUTHORIZED_RESPONSE = {
+    status: 401,
+    headers: {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+    },
+    body: '{"error":"Missing or invalid Amalgm runtime token"}',
+};
+/** runtime-auth.js:110-113 — health probes answer before auth, always. Pure over an already-parsed pathname. */
+export function isHealthPath(pathname) {
+    return pathname === '/healthz' || pathname === '/';
+}
+/** runtime-auth.js:138 — health paths plus caller-declared prefix exemptions (plain startsWith, not segment-aware). */
+export function isExemptPath(pathname, exemptPrefixes = []) {
+    return isHealthPath(pathname) || exemptPrefixes.some((prefix) => pathname.startsWith(prefix));
+}
+/**
+ * The decision skeleton of authorizeRuntimeHttp — runtime-auth.js:123-143
+ * minus the side effects (the host applies runtimeCorsHeaders to every
+ * response and writes whichever verdict comes back):
+ *  - OPTIONS is the preflight law (:126-134): 204 for loopback or
+ *    absent origins, 403 for everyone else — preflights are never
+ *    token-checked, because browsers refuse to attach credentials to
+ *    them;
+ *  - exempt paths and authorized requests pass;
+ *  - everything else gets the byte-exact 401.
+ */
+export function decideRuntimeHttp(request, policy, options = {}) {
+    if (request.method === 'OPTIONS') {
+        const loopback = isLoopbackOrigin(headerValue(request.headers, 'origin'));
+        return { kind: 'preflight', status: loopback ? 204 : 403 };
+    }
+    const exempt = isExemptPath(request.pathname, options.exemptPrefixes ?? []);
+    if (exempt || isAuthorizedRuntimeRequest(request.headers, policy))
+        return { kind: 'allow' };
+    return {
+        kind: 'reject',
+        status: UNAUTHORIZED_RESPONSE.status,
+        headers: { ...UNAUTHORIZED_RESPONSE.headers },
+        body: UNAUTHORIZED_RESPONSE.body,
+    };
+}
+/**
+ * The composed bearer guard a product calls at its HTTP boundary —
+ * hoisted from the four bricks (apps, tools, agents, browser) that each
+ * hand-rolled it, with drift including a non-timing-safe compare and a
+ * case-sensitive Bearer parse. This is those four guards as ONE law,
+ * assembled entirely from the primitives above (zero duplicated logic):
+ *
+ *  - the token arrives by {@link tokenFromHeaders} — the dedicated
+ *    header, `Authorization: Bearer` (case-insensitive scheme), or the
+ *    WS subprotocol carrier, in that precedence;
+ *  - the compare is {@link safeTokenEqual} over the injected
+ *    constant-time port (axiom 6);
+ *  - every failure — token missing, token wrong, no expected token
+ *    configured (fail closed, as the verdict law) — is the SAME
+ *    byte-exact {@link UNAUTHORIZED_RESPONSE}, so a caller never learns
+ *    which check refused it.
+ */
+export function guardBearerRequest(input) {
+    const { headers, expectedToken, timingSafeEqual } = input;
+    if (expectedToken && safeTokenEqual(tokenFromHeaders(headers), expectedToken, timingSafeEqual)) {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        status: UNAUTHORIZED_RESPONSE.status,
+        headers: { ...UNAUTHORIZED_RESPONSE.headers },
+        body: UNAUTHORIZED_RESPONSE.body,
+    };
+}
+/**
+ * runtime-auth.js:145-152 — outbound stamping: attach the runtime
+ * token to a header bag, or return the bag untouched when there is no
+ * token to attach (never an empty header).
+ */
+export function withRuntimeToken(headers, token) {
+    if (!token)
+        return headers;
+    return { ...headers, [RUNTIME_TOKEN_HEADER]: token };
+}
+/**
+ * WebSocket close codes the gateway speaks — local-gateway.js:866,873,
+ * 1061,1074 and the tunnels' denial path. 4401/4404 are the private-use
+ * mirrors of 401/404 (the WS close-code space reserves 4000-4999 for
+ * applications); 1008 is the RFC 6455 policy-violation code, used for
+ * target-port denial and unknown routes; 1011 is unexpected-condition,
+ * used when the upstream leg fails (reason = the upstream error message).
+ */
+export const WS_CLOSE_UNAUTHORIZED = { code: 4401, reason: 'Unauthorized' };
+export const WS_CLOSE_PTY_SESSION_NOT_FOUND = { code: 4404, reason: 'PTY session not found' };
+export const WS_CLOSE_POLICY_VIOLATION = 1008;
+export const WS_CLOSE_UPSTREAM_FAILURE = 1011;
+//# sourceMappingURL=auth.js.map

package/dist/transport/auth.js.map

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

package/dist/transport/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Transport — the pipe (axiom 3: it never reads the mail). Four
+ * layers, boundary-first:
+ *
+ *  - auth: the runtime auth boundary — token extraction precedence,
+ *    the verdict law, loopback CORS, the byte-exact 401, WS close
+ *    codes.
+ *  - routing: ONE routing table (axiom 4) — prefix classification,
+ *    the port-mapping and target-port laws, denial contracts. The
+ *    engine's shipped table contents live in shipped-routes.
+ *  - admission: who gets routed to at all — app refs, the serving
+ *    gate and the advertising breaker, preview-port admission, header
+ *    hygiene, log redaction.
+ *  - ingress: the event rail's receipt and signature laws.
+ */
+export * from './auth.js';
+export * from './routing.js';
+export * from './shipped-routes.js';
+export * from './admission.js';
+export * from './ingress.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC"}

package/dist/transport/index.js

@@ -0,0 +1,21 @@
+/**
+ * Transport — the pipe (axiom 3: it never reads the mail). Four
+ * layers, boundary-first:
+ *
+ *  - auth: the runtime auth boundary — token extraction precedence,
+ *    the verdict law, loopback CORS, the byte-exact 401, WS close
+ *    codes.
+ *  - routing: ONE routing table (axiom 4) — prefix classification,
+ *    the port-mapping and target-port laws, denial contracts. The
+ *    engine's shipped table contents live in shipped-routes.
+ *  - admission: who gets routed to at all — app refs, the serving
+ *    gate and the advertising breaker, preview-port admission, header
+ *    hygiene, log redaction.
+ *  - ingress: the event rail's receipt and signature laws.
+ */
+export * from './auth.js';
+export * from './routing.js';
+export * from './shipped-routes.js';
+export * from './admission.js';
+export * from './ingress.js';
+//# sourceMappingURL=index.js.map

package/dist/transport/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transport/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC"}

package/dist/transport/ingress.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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).
+ */
+import type { HeadersLike } from './auth.js';
+/** ingress.js:12 — the body cap. Counted over raw bytes as they stream in, not after assembly. */
+export declare const MAX_EVENT_BODY_BYTES: number;
+/** The over-limit rejection — ingress.js:50-53 surfaced through the generic error path (:80): status + byte-exact message. */
+export declare const EVENT_BODY_LIMIT_EXCEEDED: {
+    readonly status: 413;
+    readonly message: "Event body exceeds 2097152 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 declare const STORED_HEADERS: ReadonlySet<string>;
+/**
+ * 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 declare function storedHeaders(headers: HeadersLike | null | undefined): Record<string, string>;
+/** The receipt acknowledgment — ingress.js:73-78: 202, because acceptance is durable-queued, not processed. */
+export declare const EVENT_ACCEPTED_STATUS = 202;
+export declare function eventAcceptedBody(deliveryId: string, status: string): {
+    ok: true;
+    accepted: true;
+    deliveryId: string;
+    status: string;
+};
+/** Envelope-shaped headers: already lowercased and flattened by storedHeaders. */
+export interface FlatHeaders {
+    readonly [name: string]: string | undefined;
+}
+/** matcher.js:13-17 — HMAC proof headers, in precedence order (generic first, then GitHub's sha256, then legacy sha1). */
+export declare const HMAC_SIGNATURE_HEADERS: readonly ["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 declare const TOKEN_HEADERS: readonly ["x-amalgm-webhook-secret", "x-webhook-secret", "x-gitlab-token"];
+export interface ExtractedSignature {
+    readonly header: string;
+    readonly value: string;
+}
+/**
+ * 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 declare function extractSignature(headers: FlatHeaders): ExtractedSignature | null;
+/** The HMAC effect: hex digest of rawBody keyed by secret. The host wraps node:crypto's createHmac. */
+export type HmacHexPort = (algorithm: string, secret: string, rawBody: string) => string;
+/**
+ * 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 declare function computeSignature(secret: string, rawBody: string, hmacHex: HmacHexPort, algorithm?: string): string;
+/**
+ * matcher.js:122-128 — the human-readable source label, first
+ * recognized marker wins in this order: github → stripe → linear →
+ * gitlab → 'external'.
+ */
+export declare function pickSourceLabel(headers: FlatHeaders): 'github' | 'stripe' | 'linear' | 'gitlab' | '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 declare const PASSTHROUGH_HEADERS: readonly ["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 declare function collectPassthroughHeaders(headers: FlatHeaders): Record<string, string>;
+//# sourceMappingURL=ingress.d.ts.map