@praesidias/api-gateway 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,248 @@
+import { Condition, MappingFile, Praesidias } from '@praesidias/sdk';
+import { Server, IncomingMessage, ServerResponse } from 'node:http';
+import { Server as Server$1 } from 'node:https';
+
+/** How the upstream's credential is put on the forwarded request. */
+type CredentialPlacement = {
+    /** The header to set. Default "authorization". */
+    header?: string;
+    /** Put before the value, with a space: "Bearer", "Basic", or nothing. */
+    scheme?: string;
+};
+/**
+ * Where the upstream's credential comes from. The secret itself is never written in the config
+ * file: only where to find it.
+ *
+ * - `env`: an environment variable of the gateway's process.
+ * - `file`: a file, read again on every request. Vault Agent, the Kubernetes Secrets Store CSI
+ *   driver (AWS, Azure, Google Cloud, Vault) and Docker secrets all deliver secrets this way.
+ * - `vault`: HashiCorp Vault's key/value store, read over https (see VaultCredentialSource).
+ */
+type CredentialRule = CredentialPlacement & ({
+    from: 'env'; /** The environment variable. */
+    name: string;
+} | {
+    from: 'file'; /** An absolute path. */
+    path: string;
+} | {
+    from: 'vault';
+    /** The secret's path as Vault's API names it, for example "secret/data/payments/bank". */
+    path: string;
+    /** The field within the secret, for example "api_key". */
+    field: string;
+});
+/** A credential rule as checked: which source, and what to ask it for. */
+type CompiledCredential = CredentialPlacement & {
+    from: 'env' | 'file' | 'vault';
+    /** env: the variable. file: the path. vault: "<path>#<field>". */
+    name: string;
+};
+type RouteRule = {
+    method: string;
+    /** A path under the upstream, with `:name` for a segment that varies. */
+    path: string;
+    action?: string;
+    resource?: {
+        type?: string;
+        idFrom?: string | string[];
+    };
+    /** `arg` is `params.x`, `query.x` or `body.x`. The first rule that matches replaces the action. */
+    when?: Array<{
+        if: Condition | Condition[];
+        action: string;
+        resource?: RouteRule['resource'];
+    }>;
+    /** Values recorded with the decision, by the same paths. Nothing else from the request is. */
+    context?: string[];
+    system?: string;
+    /** Forwarded without asking Praesidias. For reads you have decided need no record. */
+    ungoverned?: boolean;
+};
+type UpstreamRule = {
+    baseUrl: string;
+    credential?: CredentialRule;
+    routes: RouteRule[];
+    /**
+     * Drop-in: the API's own hostnames. When the platform points one at this gateway (DNS, or the
+     * address the agent is given), the agent keeps calling the URL and paths it always did, with
+     * no "/<upstream>" in front. A request is matched to its upstream by its Host header.
+     */
+    hosts?: string[];
+    /**
+     * Drop-in: the agent's Praesidias key arrives in the header the agent already sends to this
+     * API, in place of the API's own credential. The gateway takes it out, asks Praesidias, and
+     * puts the real credential on instead. Only a value shaped like a Praesidias key is accepted.
+     */
+    agentKey?: {
+        header: string;
+        scheme?: string;
+    };
+};
+type GatewayConfig = {
+    /** The system these APIs are, as your areas name it. */
+    system: string;
+    listen?: {
+        host?: string;
+        port?: number;
+        /** Required to listen anywhere but this machine. */ allowRemote?: boolean;
+        /**
+         * Answer over https with this certificate and key (files, PEM). For drop-in, the certificate
+         * is for the API's own hostnames, issued by the organization's certificate authority.
+         */
+        tls?: {
+            certFile: string;
+            keyFile: string;
+        };
+    };
+    /** By the name that is the first segment of the address the agent calls. */
+    upstreams?: Record<string, UpstreamRule>;
+    /**
+     * Also answer `POST /ask`: one request that asks Praesidias about an action and returns a
+     * plain yes or no. For no-code automations (n8n, Zapier, Make, Power Automate), where one
+     * HTTPS step is all there is. Off unless set.
+     */
+    ask?: boolean;
+};
+declare class ConfigError extends Error {
+}
+type CompiledRoute = RouteRule & {
+    method: string;
+    match: RegExp;
+    params: string[];
+    id: string;
+};
+type CompiledUpstream = {
+    name: string;
+    base: URL;
+    credential: CompiledCredential | null;
+    routes: CompiledRoute[];
+    mapping: MappingFile;
+    hosts: string[];
+    agentKey: {
+        header: string;
+        scheme?: string;
+    } | null;
+};
+type Compiled = {
+    system: string;
+    host: string;
+    port: number;
+    ask: boolean;
+    upstreams: Map<string, CompiledUpstream>;
+    /** Drop-in: an upstream by one of its own hostnames. */
+    hosts: Map<string, CompiledUpstream>;
+    tls: {
+        certFile: string;
+        keyFile: string;
+    } | null;
+};
+/** Checks the whole file at start, so a mistake stops the gateway instead of surfacing mid-request. */
+declare function compileConfig(raw: unknown): Compiled;
+declare function loadConfig(path: string): Compiled;
+
+/**
+ * Where the gateway gets an upstream API's credential at the moment it forwards a request.
+ * The agent never has it: the agent only ever holds its Praesidias key.
+ *
+ * `get` is asked each time, so a source may rotate what it returns. Return undefined when
+ * there is nothing under that name; the request is then refused, never sent without one.
+ */
+type CredentialSource = {
+    get(name: string): Promise<string | undefined> | string | undefined;
+};
+/** Reads credentials from this process's environment. */
+declare class EnvCredentialSource implements CredentialSource {
+    private readonly env;
+    constructor(env?: NodeJS.ProcessEnv);
+    get(name: string): string | undefined;
+}
+/** Why a credential could not be had. Names only: never a secret, a token or a file's contents. */
+type Note = (line: string) => void;
+/**
+ * Reads a credential from a file, read again on every request so a rotated secret is picked up
+ * without a restart. This is how most secret stores hand a secret to a process: Vault Agent,
+ * the Kubernetes Secrets Store CSI driver (for AWS, Azure, Google Cloud or Vault), and Docker
+ * secrets all write it to a file. The name asked for is the file's path.
+ */
+declare class FileCredentialSource implements CredentialSource {
+    private readonly note;
+    constructor(note?: Note);
+    get(path: string): Promise<string | undefined>;
+}
+type VaultOptions = {
+    env?: NodeJS.ProcessEnv;
+    /** How long a secret read from Vault is reused, in milliseconds. Default 60 s; 0 reads every time. */
+    cacheMs?: number;
+    /** How long Vault may take, in milliseconds. Default 5 s. */
+    timeoutMs?: number;
+    note?: Note;
+    /** For tests. */
+    fetch?: typeof fetch;
+};
+/**
+ * Reads a credential from HashiCorp Vault's key/value store (version 2, or version 1), over
+ * https. The name asked for is `<path>#<field>`, for example `secret/data/payments/bank#api_key`.
+ *
+ * Vault is found from the standard variables: VAULT_ADDR, VAULT_TOKEN or VAULT_TOKEN_FILE (the
+ * file Vault Agent keeps a fresh token in, read again each time), and VAULT_NAMESPACE. A private
+ * certificate authority for Vault is trusted with NODE_EXTRA_CA_CERTS, as for any Node process.
+ *
+ * A secret is reused for a short while so Vault is not asked on every request. When it is time
+ * to ask again and Vault cannot answer, nothing is returned and the request is refused: an
+ * expired secret is never used.
+ */
+declare class VaultCredentialSource implements CredentialSource {
+    private readonly env;
+    private readonly cacheMs;
+    private readonly timeoutMs;
+    private readonly note;
+    private readonly send;
+    private readonly cache;
+    private readonly reading;
+    constructor(options?: VaultOptions);
+    get(name: string): Promise<string | undefined>;
+    private token;
+    private read;
+}
+
+type ApiGatewayOptions = {
+    config: Compiled;
+    /** The Praesidias address. Must be https, except on this machine. */
+    praesidiasUrl: string;
+    /** Where "env" credentials come from. Default: this process's environment. */
+    credentials?: CredentialSource;
+    /** Settings for "vault" credentials (Vault itself is found from VAULT_ADDR and friends). */
+    vault?: Omit<VaultOptions, 'note'>;
+    /** One line per request: method, route, action, outcome. Never a key, a credential or a body. */
+    log?: (line: string) => void;
+    /** The header the agent puts its Praesidias key in. Default "x-praesidias-key". */
+    keyHeader?: string;
+    /** Largest request body accepted, in bytes. Default 1 MB. */
+    maxBodyBytes?: number;
+    /** How long an upstream may take, in milliseconds. Default 30 s. */
+    upstreamTimeoutMs?: number;
+    /** For tests. */
+    fetch?: typeof fetch;
+    sdkOptions?: ConstructorParameters<typeof Praesidias>[0];
+};
+/**
+ * A gateway in front of the outside APIs an agent calls.
+ *
+ * The agent calls `http://<gateway>/<upstream>/<path>` with its Praesidias key. The gateway
+ * finds the configured route, asks Praesidias whether this agent may do that action on that
+ * resource, and only then forwards the request, adding the API's own credential. The agent
+ * never holds that credential, so it cannot reach the API any other way.
+ *
+ * It fails closed at every step: no route, no key, no answer from Praesidias, or no credential
+ * all mean the request is not sent.
+ */
+declare function createApiGateway(options: ApiGatewayOptions): Server;
+/**
+ * The gateway as a server: over https when the config has "listen.tls" (the certificate and key
+ * are read here, once), otherwise plain http as `createApiGateway`.
+ */
+declare function createApiGatewayServer(options: ApiGatewayOptions): Server | Server$1;
+/** The request handler, for any http or https server. Everything the gateway does is here. */
+declare function createApiGatewayHandler(options: ApiGatewayOptions): (req: IncomingMessage, res: ServerResponse) => void;
+
+export { type ApiGatewayOptions, type Compiled, type CompiledCredential, ConfigError, type CredentialRule, type CredentialSource, EnvCredentialSource, FileCredentialSource, type GatewayConfig, type RouteRule, type UpstreamRule, VaultCredentialSource, type VaultOptions, compileConfig, createApiGateway, createApiGatewayHandler, createApiGatewayServer, loadConfig };

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+import { Condition, MappingFile, Praesidias } from '@praesidias/sdk';
+import { Server, IncomingMessage, ServerResponse } from 'node:http';
+import { Server as Server$1 } from 'node:https';
+
+/** How the upstream's credential is put on the forwarded request. */
+type CredentialPlacement = {
+    /** The header to set. Default "authorization". */
+    header?: string;
+    /** Put before the value, with a space: "Bearer", "Basic", or nothing. */
+    scheme?: string;
+};
+/**
+ * Where the upstream's credential comes from. The secret itself is never written in the config
+ * file: only where to find it.
+ *
+ * - `env`: an environment variable of the gateway's process.
+ * - `file`: a file, read again on every request. Vault Agent, the Kubernetes Secrets Store CSI
+ *   driver (AWS, Azure, Google Cloud, Vault) and Docker secrets all deliver secrets this way.
+ * - `vault`: HashiCorp Vault's key/value store, read over https (see VaultCredentialSource).
+ */
+type CredentialRule = CredentialPlacement & ({
+    from: 'env'; /** The environment variable. */
+    name: string;
+} | {
+    from: 'file'; /** An absolute path. */
+    path: string;
+} | {
+    from: 'vault';
+    /** The secret's path as Vault's API names it, for example "secret/data/payments/bank". */
+    path: string;
+    /** The field within the secret, for example "api_key". */
+    field: string;
+});
+/** A credential rule as checked: which source, and what to ask it for. */
+type CompiledCredential = CredentialPlacement & {
+    from: 'env' | 'file' | 'vault';
+    /** env: the variable. file: the path. vault: "<path>#<field>". */
+    name: string;
+};
+type RouteRule = {
+    method: string;
+    /** A path under the upstream, with `:name` for a segment that varies. */
+    path: string;
+    action?: string;
+    resource?: {
+        type?: string;
+        idFrom?: string | string[];
+    };
+    /** `arg` is `params.x`, `query.x` or `body.x`. The first rule that matches replaces the action. */
+    when?: Array<{
+        if: Condition | Condition[];
+        action: string;
+        resource?: RouteRule['resource'];
+    }>;
+    /** Values recorded with the decision, by the same paths. Nothing else from the request is. */
+    context?: string[];
+    system?: string;
+    /** Forwarded without asking Praesidias. For reads you have decided need no record. */
+    ungoverned?: boolean;
+};
+type UpstreamRule = {
+    baseUrl: string;
+    credential?: CredentialRule;
+    routes: RouteRule[];
+    /**
+     * Drop-in: the API's own hostnames. When the platform points one at this gateway (DNS, or the
+     * address the agent is given), the agent keeps calling the URL and paths it always did, with
+     * no "/<upstream>" in front. A request is matched to its upstream by its Host header.
+     */
+    hosts?: string[];
+    /**
+     * Drop-in: the agent's Praesidias key arrives in the header the agent already sends to this
+     * API, in place of the API's own credential. The gateway takes it out, asks Praesidias, and
+     * puts the real credential on instead. Only a value shaped like a Praesidias key is accepted.
+     */
+    agentKey?: {
+        header: string;
+        scheme?: string;
+    };
+};
+type GatewayConfig = {
+    /** The system these APIs are, as your areas name it. */
+    system: string;
+    listen?: {
+        host?: string;
+        port?: number;
+        /** Required to listen anywhere but this machine. */ allowRemote?: boolean;
+        /**
+         * Answer over https with this certificate and key (files, PEM). For drop-in, the certificate
+         * is for the API's own hostnames, issued by the organization's certificate authority.
+         */
+        tls?: {
+            certFile: string;
+            keyFile: string;
+        };
+    };
+    /** By the name that is the first segment of the address the agent calls. */
+    upstreams?: Record<string, UpstreamRule>;
+    /**
+     * Also answer `POST /ask`: one request that asks Praesidias about an action and returns a
+     * plain yes or no. For no-code automations (n8n, Zapier, Make, Power Automate), where one
+     * HTTPS step is all there is. Off unless set.
+     */
+    ask?: boolean;
+};
+declare class ConfigError extends Error {
+}
+type CompiledRoute = RouteRule & {
+    method: string;
+    match: RegExp;
+    params: string[];
+    id: string;
+};
+type CompiledUpstream = {
+    name: string;
+    base: URL;
+    credential: CompiledCredential | null;
+    routes: CompiledRoute[];
+    mapping: MappingFile;
+    hosts: string[];
+    agentKey: {
+        header: string;
+        scheme?: string;
+    } | null;
+};
+type Compiled = {
+    system: string;
+    host: string;
+    port: number;
+    ask: boolean;
+    upstreams: Map<string, CompiledUpstream>;
+    /** Drop-in: an upstream by one of its own hostnames. */
+    hosts: Map<string, CompiledUpstream>;
+    tls: {
+        certFile: string;
+        keyFile: string;
+    } | null;
+};
+/** Checks the whole file at start, so a mistake stops the gateway instead of surfacing mid-request. */
+declare function compileConfig(raw: unknown): Compiled;
+declare function loadConfig(path: string): Compiled;
+
+/**
+ * Where the gateway gets an upstream API's credential at the moment it forwards a request.
+ * The agent never has it: the agent only ever holds its Praesidias key.
+ *
+ * `get` is asked each time, so a source may rotate what it returns. Return undefined when
+ * there is nothing under that name; the request is then refused, never sent without one.
+ */
+type CredentialSource = {
+    get(name: string): Promise<string | undefined> | string | undefined;
+};
+/** Reads credentials from this process's environment. */
+declare class EnvCredentialSource implements CredentialSource {
+    private readonly env;
+    constructor(env?: NodeJS.ProcessEnv);
+    get(name: string): string | undefined;
+}
+/** Why a credential could not be had. Names only: never a secret, a token or a file's contents. */
+type Note = (line: string) => void;
+/**
+ * Reads a credential from a file, read again on every request so a rotated secret is picked up
+ * without a restart. This is how most secret stores hand a secret to a process: Vault Agent,
+ * the Kubernetes Secrets Store CSI driver (for AWS, Azure, Google Cloud or Vault), and Docker
+ * secrets all write it to a file. The name asked for is the file's path.
+ */
+declare class FileCredentialSource implements CredentialSource {
+    private readonly note;
+    constructor(note?: Note);
+    get(path: string): Promise<string | undefined>;
+}
+type VaultOptions = {
+    env?: NodeJS.ProcessEnv;
+    /** How long a secret read from Vault is reused, in milliseconds. Default 60 s; 0 reads every time. */
+    cacheMs?: number;
+    /** How long Vault may take, in milliseconds. Default 5 s. */
+    timeoutMs?: number;
+    note?: Note;
+    /** For tests. */
+    fetch?: typeof fetch;
+};
+/**
+ * Reads a credential from HashiCorp Vault's key/value store (version 2, or version 1), over
+ * https. The name asked for is `<path>#<field>`, for example `secret/data/payments/bank#api_key`.
+ *
+ * Vault is found from the standard variables: VAULT_ADDR, VAULT_TOKEN or VAULT_TOKEN_FILE (the
+ * file Vault Agent keeps a fresh token in, read again each time), and VAULT_NAMESPACE. A private
+ * certificate authority for Vault is trusted with NODE_EXTRA_CA_CERTS, as for any Node process.
+ *
+ * A secret is reused for a short while so Vault is not asked on every request. When it is time
+ * to ask again and Vault cannot answer, nothing is returned and the request is refused: an
+ * expired secret is never used.
+ */
+declare class VaultCredentialSource implements CredentialSource {
+    private readonly env;
+    private readonly cacheMs;
+    private readonly timeoutMs;
+    private readonly note;
+    private readonly send;
+    private readonly cache;
+    private readonly reading;
+    constructor(options?: VaultOptions);
+    get(name: string): Promise<string | undefined>;
+    private token;
+    private read;
+}
+
+type ApiGatewayOptions = {
+    config: Compiled;
+    /** The Praesidias address. Must be https, except on this machine. */
+    praesidiasUrl: string;
+    /** Where "env" credentials come from. Default: this process's environment. */
+    credentials?: CredentialSource;
+    /** Settings for "vault" credentials (Vault itself is found from VAULT_ADDR and friends). */
+    vault?: Omit<VaultOptions, 'note'>;
+    /** One line per request: method, route, action, outcome. Never a key, a credential or a body. */
+    log?: (line: string) => void;
+    /** The header the agent puts its Praesidias key in. Default "x-praesidias-key". */
+    keyHeader?: string;
+    /** Largest request body accepted, in bytes. Default 1 MB. */
+    maxBodyBytes?: number;
+    /** How long an upstream may take, in milliseconds. Default 30 s. */
+    upstreamTimeoutMs?: number;
+    /** For tests. */
+    fetch?: typeof fetch;
+    sdkOptions?: ConstructorParameters<typeof Praesidias>[0];
+};
+/**
+ * A gateway in front of the outside APIs an agent calls.
+ *
+ * The agent calls `http://<gateway>/<upstream>/<path>` with its Praesidias key. The gateway
+ * finds the configured route, asks Praesidias whether this agent may do that action on that
+ * resource, and only then forwards the request, adding the API's own credential. The agent
+ * never holds that credential, so it cannot reach the API any other way.
+ *
+ * It fails closed at every step: no route, no key, no answer from Praesidias, or no credential
+ * all mean the request is not sent.
+ */
+declare function createApiGateway(options: ApiGatewayOptions): Server;
+/**
+ * The gateway as a server: over https when the config has "listen.tls" (the certificate and key
+ * are read here, once), otherwise plain http as `createApiGateway`.
+ */
+declare function createApiGatewayServer(options: ApiGatewayOptions): Server | Server$1;
+/** The request handler, for any http or https server. Everything the gateway does is here. */
+declare function createApiGatewayHandler(options: ApiGatewayOptions): (req: IncomingMessage, res: ServerResponse) => void;
+
+export { type ApiGatewayOptions, type Compiled, type CompiledCredential, ConfigError, type CredentialRule, type CredentialSource, EnvCredentialSource, FileCredentialSource, type GatewayConfig, type RouteRule, type UpstreamRule, VaultCredentialSource, type VaultOptions, compileConfig, createApiGateway, createApiGatewayHandler, createApiGatewayServer, loadConfig };