@claxedo/workspace-relay 0.1.0

package/dist/main.d.ts

@@ -0,0 +1,160 @@
+import { type WorkspaceRelayBunDrainController } from "./bun";
+import { type WorkspaceRelayDirectory } from "./directory";
+import type { RelayHostPublicKey, RuntimeAccessTokenActiveResult } from "./server";
+import type { RelayKey } from "./auth";
+/**
+ * Production fail-closed gate for the relay → claxedo-server resolver channel.
+ *
+ * If `CLAXEDO_RELAY_RESOLVER_TOKEN` is missing/empty in production the relay
+ * would otherwise call the resolver unauthenticated. Refuse to boot.
+ *
+ * Allowed in dev/test for ergonomics — the resolver itself falls back to a
+ * loopback-only check when no token is configured.
+ */
+export type ValidateProductionEnvInput = {
+    NODE_ENV?: string | undefined;
+    CLAXEDO_RELAY_RESOLVER_TOKEN?: string | undefined;
+};
+export type ValidateProductionEnvResult = {
+    ok: true;
+} | {
+    ok: false;
+    exitCode: 2;
+    message: string;
+};
+export declare function validateProductionEnv(env: ValidateProductionEnvInput): ValidateProductionEnvResult;
+/**
+ * Resolve the verification key (or keyset resolver) for Runtime Access Tokens.
+ *
+ * Precedence: `CLAXEDO_CONTROL_PLANE_JWKS_URL` > `CLAXEDO_RUNTIME_ACCESS_TOKEN_PUBLIC_KEY_PEM`.
+ * The PEM env var is kept as a fallback so JWKS rollouts can ship gradually.
+ *
+ * Exported for tests.
+ */
+export type LoadRuntimeAccessKeyEnv = {
+    CLAXEDO_CONTROL_PLANE_JWKS_URL?: string | undefined;
+    CLAXEDO_RUNTIME_ACCESS_TOKEN_PUBLIC_KEY_PEM?: string | undefined;
+};
+export declare function loadRuntimeAccessKeyOrJwks(env: LoadRuntimeAccessKeyEnv): Promise<RelayKey>;
+/**
+ * Resolve the RHT key material — both the private key used to sign RHTs and
+ * the public key(s) we publish at `/.well-known/jwks.json`.
+ *
+ * Precedence for the public counterpart:
+ *   1. `CLAXEDO_RELAY_HOST_PUBLIC_KEY_PEM` (explicit override; useful when
+ *      the private key is held in an HSM-style import that strips public bits).
+ *   2. Derived from the private key via `exportJWK` (works because we now
+ *      load the private key with `extractable: true`).
+ *
+ * `kid` is the explicit `CLAXEDO_RELAY_HOST_KID` env var if set, otherwise
+ * SHA-256(public-key-x).slice(0, 16). Mint and JWKS use the same derivation
+ * so they always agree.
+ *
+ * `next` is optional and is included in JWKS only — never used to mint. It
+ * exists to support rolling rotation: publish the next key, drain the
+ * current one, swap signing key, retire the old.
+ *
+ * Exported for tests.
+ */
+export type LoadRelayHostKeyMaterialEnv = {
+    /**
+     * Used to gate the production fail-closed check for the RHT signing key.
+     * If `production` and no signing key PEM is configured, the loader exits
+     * with code 2 rather than silently generating an ephemeral key (which
+     * would be different on every instance and break verification across a
+     * multi-instance deploy).
+     *
+     * Note: T2's `validateProductionEnv` is the canonical home for top-level
+     * env validation, but this check lives here because the loader already
+     * inspects the signing-key env var and the failure mode is local. The
+     * boot path could optionally re-route through `validateProductionEnv` in
+     * a future refactor.
+     */
+    NODE_ENV?: string | undefined;
+    CLAXEDO_RELAY_HOST_SIGNING_KEY_PEM?: string | undefined;
+    CLAXEDO_RELAY_HOST_PUBLIC_KEY_PEM?: string | undefined;
+    CLAXEDO_RELAY_HOST_NEXT_PUBLIC_KEY_PEM?: string | undefined;
+    CLAXEDO_RELAY_HOST_KID?: string | undefined;
+    CLAXEDO_RELAY_HOST_NEXT_KID?: string | undefined;
+};
+export type RelayHostKeyMaterial = {
+    privateKey: CryptoKey;
+    current: RelayHostPublicKey;
+    next?: RelayHostPublicKey;
+};
+export declare function loadRelayHostKeyMaterial(env: LoadRelayHostKeyMaterialEnv): Promise<RelayHostKeyMaterial>;
+/**
+ * T16: parse `CLAXEDO_RELAY_AUDIT_ACCEPT_SAMPLE_RATE` into a number in [0, 1].
+ * Falls back to a NODE_ENV-gated default (production: 0.1, dev/test: 1.0) if
+ * unset, empty, or out of range. Exported for tests.
+ */
+export type ParseAuditAcceptSampleRateEnv = {
+    CLAXEDO_RELAY_AUDIT_ACCEPT_SAMPLE_RATE?: string | undefined;
+    NODE_ENV?: string | undefined;
+};
+export declare function parseAuditAcceptSampleRate(env: ParseAuditAcceptSampleRateEnv): number;
+/**
+ * T31: parse the `CLAXEDO_RELAY_METRICS_TOKEN` env var. Returns `undefined`
+ * for missing/empty/whitespace-only values so the relay can fall back to its
+ * loopback-only `/metrics` access policy.
+ */
+export type ParseMetricsTokenEnv = {
+    CLAXEDO_RELAY_METRICS_TOKEN?: string | undefined;
+};
+export declare function parseMetricsToken(env: ParseMetricsTokenEnv): string | undefined;
+export type RevocationLookupArgs = {
+    jti: string;
+    workspaceId: string;
+    hostId: string;
+};
+export type RevocationLookup = (args: RevocationLookupArgs) => Promise<RuntimeAccessTokenActiveResult>;
+export type CachedRevocationOptions = {
+    /** TTL in milliseconds for cached revocation responses. Defaults to 10_000. */
+    ttlMs?: number;
+    /** Clock injection for tests. Defaults to `Date.now`. */
+    now?: () => number;
+};
+/**
+ * Wraps a revocation lookup with a small in-memory cache keyed by `jti`.
+ * Both positive and negative results are cached for the full TTL — this is
+ * safe because RAT revocation lag is bounded by the same TTL by design.
+ */
+export declare function createCachedRevocationClient(inner: RevocationLookup, options?: CachedRevocationOptions): RevocationLookup;
+/**
+ * T9: graceful SIGTERM drain wiring.
+ *
+ * On `SIGTERM` (or `SIGINT` for local dev) the relay must:
+ *   1. Flip the drain flag so `/health` reports 503 and Fly removes the
+ *      machine from routing, and so new HTTP requests + tunnel registrations
+ *      fast-path to 503 before doing any auth or upstream work.
+ *   2. Wait up to `drainTimeoutMs` (default 30 s, override via
+ *      `CLAXEDO_RELAY_DRAIN_TIMEOUT_MS`) for the in-flight tunnel HTTP
+ *      response map to empty across every connected host tunnel.
+ *   3. Release the directory's TTL sweep timer (T18 added `dispose()`) so
+ *      the process can exit cleanly without a dangling `setInterval`.
+ *   4. Exit with code 0.
+ *
+ * Exposed for tests so the trigger logic can be exercised without actually
+ * raising signals or stopping the process. Pass `register: false` in tests
+ * to skip the real `process.on(...)` registration.
+ */
+export type ShutdownDrainHandlerOptions = {
+    drain: WorkspaceRelayBunDrainController;
+    directory: Pick<WorkspaceRelayDirectory, "dispose">;
+    drainTimeoutMs: number;
+    /** Defaults to `process.exit`. Override for tests. */
+    exit?: (code?: number) => void;
+    /** Defaults to a no-op log. */
+    log?: (message: string) => void;
+    /** When true (default), register `SIGTERM` and `SIGINT` handlers on `process`. */
+    register?: boolean;
+    /** Signals to listen for. Defaults to `["SIGTERM", "SIGINT"]`. */
+    signals?: NodeJS.Signals[];
+    /** Defaults to a no-op (we let Bun.serve get GC'd as part of process exit). */
+    stopServer?: () => Promise<void> | void;
+};
+export type ShutdownDrainHandle = {
+    trigger(): Promise<void>;
+    isShuttingDown(): boolean;
+};
+export declare function installShutdownDrainHandler(options: ShutdownDrainHandlerOptions): ShutdownDrainHandle;