@wayai/executor-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,336 @@
+/** The cached outcome of a completed request, replayed verbatim on a duplicate delivery. */
+interface StoredResult {
+    status: number;
+    body: string;
+    contentType?: string;
+}
+type ClaimResult = {
+    state: 'fresh';
+} | {
+    state: 'in_progress';
+} | {
+    state: 'done';
+    result: StoredResult;
+};
+/**
+ * Idempotency store: dedupe deliveries by key with first-request-wins semantics. `MemoryStore` is the
+ * default; supply your own (Redis / a Durable Object / a DB) when running more than one instance, since
+ * an in-memory store is per-process.
+ */
+interface IdempotencyStore {
+    /** Atomically claim a key. `fresh` ⇒ caller proceeds; `in_progress`/`done` ⇒ don't re-run. */
+    claim(key: string, ttlSec: number): Promise<ClaimResult>;
+    /** Record the terminal result so future duplicates replay it. */
+    complete(key: string, result: StoredResult, ttlSec: number): Promise<void>;
+    /** Release a key after a retriable failure so the next attempt re-runs (don't cache failures). */
+    fail(key: string): Promise<void>;
+}
+
+/** Framework-neutral request the adapters hand to the executor. `rawBody` is the RAW bytes as a string. */
+interface NormalizedRequest {
+    method: string;
+    path: string;
+    headers: Headers | Record<string, string | string[] | undefined>;
+    rawBody: string;
+}
+interface NormalizedResponse {
+    status: number;
+    body: string;
+    contentType: string;
+}
+/** Verified request context passed to your handler. Never contains the signing secret. */
+interface ExecutorContext {
+    id: string;
+    idempotencyKey?: string;
+    deliveryId?: string;
+    timestamp: number;
+    body: string;
+}
+/** Your business logic. Return a `StoredResult` (cached for idempotent replays) or nothing (→ 204). */
+type ExecutorHandler = (ctx: ExecutorContext) => Promise<StoredResult | void> | StoredResult | void;
+interface CreateExecutorOptions {
+    /** HMAC signing secret shared with Rekor. */
+    secret: string;
+    handler: ExecutorHandler;
+    /** Idempotency store. Default: a per-process {@link MemoryStore}. */
+    store?: IdempotencyStore;
+    /** Clock-skew tolerance (seconds, both directions). Default 300; clamped to ≥1. */
+    toleranceSec?: number;
+    /** Skip signature/skew verification (LOCAL DEV ONLY). Dedup still applies if headers are present. */
+    devBypass?: boolean;
+    /** Idempotency record TTL (seconds). Default 86400 (24h). */
+    idempotencyTtlSec?: number;
+    /** Reports unexpected handler errors. MUST NOT log secrets/PII — it never receives the secret. */
+    onError?: (err: unknown, ctx?: ExecutorContext) => void;
+    /**
+     * Reproduce the path Rekor SIGNED when a reverse proxy rewrites it. Must return the exact
+     * `pathname+search` Rekor used (see README path-matching), not necessarily the incoming path.
+     */
+    pathOverride?: (req: NormalizedRequest) => string;
+}
+interface Executor {
+    handle(req: NormalizedRequest): Promise<NormalizedResponse>;
+}
+declare function createExecutor(opts: CreateExecutorOptions): Executor;
+
+/**
+ * Wrap an {@link Executor} as a Fetch-API handler `(Request) => Promise<Response>` — works on Hono,
+ * Next.js route handlers, Cloudflare Workers, Deno, and Bun.
+ *
+ * Reads the RAW body via `req.text()` BEFORE any parsing (verifying a re-stringified parsed body would
+ * fail). The signed `path` is `new URL(req.url).pathname + search`; if a reverse proxy rewrites the
+ * path, pass `pathOverride` to `createExecutor`.
+ */
+declare function toFetchHandler(executor: Executor): (req: Request) => Promise<Response>;
+
+/**
+ * Minimal structural shapes of Node's `http.IncomingMessage` / `http.ServerResponse` (and Express's
+ * `req`/`res`). Declared structurally so the package imports no Node built-ins at runtime.
+ */
+interface NodeReq extends AsyncIterable<unknown> {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+interface NodeRes {
+    writeHead(status: number, headers?: Record<string, string>): unknown;
+    end(chunk?: string): unknown;
+}
+/**
+ * Wrap an {@link Executor} as a Node/Express handler `(req, res) => Promise<void>`.
+ *
+ * IMPORTANT: this reads the RAW request stream itself, so it MUST run BEFORE any body parser
+ * (`express.json()`, `body-parser`, …). If a parser has already consumed the stream, the raw bytes are
+ * gone and verification fails. Mount this on the Rekor route before such middleware.
+ *
+ * The signed `path` comes from `req.url` (already `pathname+search`); use `pathOverride` for proxies.
+ */
+declare function toNodeHandler(executor: Executor): (req: NodeReq, res: NodeRes) => Promise<void>;
+
+/**
+ * Rekor "Signing v1" canonical — the exact string Rekor HMAC-signs for every request it sends
+ * (trigger webhooks + signed proxied calls). Ported verbatim from the backend's
+ * `workers/shared/src/signing.ts`; kept byte-identical by the cross-package conformance vector.
+ *
+ * canonical = ["v1", id, String(unixTimestamp), method, path, body].join("\n")
+ *
+ * SECURITY INVARIANT: newline-joined; the only data-influenced field, `body`, is LAST, and every
+ * other field is provably newline-free (the "v1" literal, an integer, a uuid/hex id, an HTTP method
+ * token, and a URL pathname+search). The signature binds method + path so it can't be replayed as a
+ * different request.
+ */
+declare const SIGNING_SCHEME = "v1";
+interface SignedParts {
+    /** Stable message id — `X-Data-Id` (= delivery id on webhooks, idempotency key on proxied writes). */
+    id: string;
+    /** `X-Data-Timestamp`, unix seconds (integer). */
+    timestamp: number;
+    /** HTTP method (`POST` for trigger webhooks). */
+    method: string;
+    /** Request path: `new URL(receiverUrl).pathname + search`. */
+    path: string;
+    /** Exact raw request body string (`""` when none). */
+    body: string;
+}
+/** Build the canonical signing string. Component order and the `v1` prefix are part of the wire. */
+declare function buildCanonical(parts: SignedParts): string;
+/** Current unix time in whole seconds (Standard Webhooks convention). `nowMs` override for tests. */
+declare function unixSeconds(nowMs?: number): number;
+
+/**
+ * Verify a Rekor "Signing v1" request: HMAC over the canonical, plus timestamp-skew enforcement
+ * (the receiver's job — Rekor only emits). All inputs are the raw request bits the adapter extracts.
+ */
+
+/** Lowercased header names Rekor emits. */
+declare const DATA_HEADERS: {
+    readonly signature: "x-data-signature";
+    readonly timestamp: "x-data-timestamp";
+    readonly id: "x-data-id";
+    readonly idempotencyKey: "x-data-idempotency-key";
+    readonly deliveryId: "x-data-delivery-id";
+    readonly credentialUrl: "x-data-credential-url";
+    readonly credentialToken: "x-data-credential-token";
+    readonly credentialNames: "x-data-credential-names";
+};
+/**
+ * Max `scheme,hex` candidates we'll HMAC-check from one `X-Data-Signature` header. Rekor emits one
+ * (two during a future key rotation); the cap stops a hostile header with thousands of entries from
+ * forcing thousands of HMACs per request.
+ */
+declare const MAX_SIG_ENTRIES = 4;
+/**
+ * Verify a signature header value (`X-Data-Signature`) against the canonical of `parts`. The header
+ * is a space-delimited list of `scheme,hex` entries; returns true if any `v1` entry matches (constant-
+ * time compare). Malformed/empty/unknown-scheme entries are skipped, never throw. Candidates beyond
+ * `MAX_SIG_ENTRIES` are ignored. Does NOT check timestamp skew (see {@link verify}).
+ */
+declare function verifySignatureHeader(secret: string, parts: SignedParts, header: string): Promise<boolean>;
+type VerifyResult = {
+    ok: true;
+    id: string;
+    timestamp: number;
+    idempotencyKey?: string;
+    deliveryId?: string;
+    body: string;
+} | {
+    ok: false;
+    reason: 'missing_signature' | 'invalid_signature' | 'stale_timestamp' | 'malformed';
+};
+interface VerifyInput {
+    /** The HMAC signing secret shared with Rekor (the trigger/source signing secret). */
+    secret: string;
+    /** Request headers — a Fetch `Headers` or a plain object (case-insensitive lookup either way). */
+    headers: Headers | Record<string, string | string[] | undefined>;
+    /** HTTP method of the incoming request. */
+    method: string;
+    /** Request path the signature was computed over: `pathname + search` (see README path-matching). */
+    path: string;
+    /** RAW request body bytes as a string — NEVER a re-stringified parsed object. */
+    rawBody: string;
+    /** Allowed clock skew in seconds (both directions). A finite value is clamped to ≥1 (never 0);
+     *  unset / NaN / Infinity fall back to the 300s default (a bad value can't disable the window). */
+    toleranceSec?: number;
+    /** Override "now" in ms (tests). */
+    now?: number;
+}
+/**
+ * Verify an inbound Rekor request end to end: signature present + valid, and timestamp within the
+ * skew window. Returns a discriminated result; never throws on bad input.
+ */
+declare function verify(input: VerifyInput): Promise<VerifyResult>;
+
+/**
+ * Sign a request TO Rekor — the inverse of the executor's verify side. Use this when an executor POSTs
+ * a result back to a Rekor inbound webhook (the async write-back leg): Rekor's inbound webhook ingest verifies a Signing v1
+ * signature, and this produces it from the inbound webhook's shared secret.
+ *
+ * Returns the three headers to attach (`X-Data-Signature`, `X-Data-Timestamp`, `X-Data-Id`). The
+ * canonical is byte-identical to the verify side (the cross-package conformance vector guards drift).
+ */
+interface SignRequestInput {
+    /** HMAC shared secret for the target Rekor inbound webhook. */
+    secret: string;
+    /** HTTP method of the request being signed (e.g. 'POST'). */
+    method: string;
+    /** Full target URL — its `pathname + search` is bound into the signature. */
+    url: string;
+    /** Raw request body string (default `''`). MUST be the exact bytes sent. */
+    body?: string;
+    /** Message id → `X-Data-Id`, bound into the signature. Default: a generated UUID. */
+    id?: string;
+    /** Unix seconds → `X-Data-Timestamp`. Default: now. */
+    timestamp?: number;
+}
+interface SignedHeaders {
+    'X-Data-Signature': string;
+    'X-Data-Timestamp': string;
+    'X-Data-Id': string;
+}
+/** Sign a request to Rekor and return the headers to attach. */
+declare function signRequest(input: SignRequestInput): Promise<SignedHeaders>;
+
+/**
+ * Executor credential pull — the client side of Rekor's scoped, single-use binary-credential delivery.
+ *
+ * When a Rekor source declares `executor_secrets`, every proxied dispatch to the executor carries
+ * `X-Data-Credential-Url`/`-Token`/`-Names`. The executor calls `fetchExecutorCredential` with the
+ * INBOUND request to pull a declared credential by name (e.g. an mTLS client cert it must present to a
+ * downstream upstream). The grant is single-use per name and short-lived, so fetch each credential ONCE
+ * per invocation and reuse the value — a re-pull of the same name fails (the grant is already claimed).
+ *
+ * The returned `value` is delivered verbatim (Rekor stores binary credentials base64-encoded); decode it
+ * per `contentType` (e.g. base64-decode an `application/x-pkcs12` bundle). This helper never decodes.
+ *
+ * SECURITY: call this ONLY from a handler whose inbound request the SDK has already verified (e.g. inside
+ * `createExecutor`'s handler). The grant headers are NOT part of the request's HMAC signature, so anything
+ * that can rewrite headers in front of your executor (a TLS-terminating proxy/gateway) could swap the
+ * callback URL. Pass `allowedOrigins` (your Rekor origin, e.g. `['https://api.rekor.pro']`) to reject a
+ * rewritten URL — recommended whenever your executor sits behind such an intermediary.
+ */
+/** A pulled credential. `value` is delivered verbatim (base64 for binary); decode per `contentType`. */
+interface ExecutorCredential {
+    name: string;
+    contentType: string;
+    value: string;
+}
+interface FetchCredentialOptions {
+    /** Override the fetch implementation (defaults to the global `fetch`). */
+    fetchImpl?: typeof fetch;
+    /**
+     * If set (and non-empty), the callback URL's origin must be one of these — rejects a URL rewritten in
+     * transit (the grant headers are NOT covered by the request signature). Pass your Rekor origin(s),
+     * e.g. `['https://api.rekor.pro']`. Recommended when the executor sits behind a TLS-terminating proxy.
+     */
+    allowedOrigins?: string[];
+}
+/** Anything carrying the inbound request headers: a NormalizedRequest, a Fetch `Request`, or raw headers. */
+type HeaderSource = Headers | Record<string, string | string[] | undefined> | {
+    headers: Headers | Record<string, string | string[] | undefined>;
+};
+/**
+ * Pull a declared credential by name from Rekor, using the grant advertised on the inbound dispatch.
+ * Throws `ExecutorError` if the request carries no grant, the name isn't in the grant, or the pull is
+ * denied/fails. A 403 (grant invalid/expired/already-used) is never retried; a transient 5xx/network
+ * error is retried once.
+ */
+declare function fetchExecutorCredential(source: HeaderSource, name: string, opts?: FetchCredentialOptions): Promise<ExecutorCredential>;
+
+declare class MemoryStore implements IdempotencyStore {
+    private readonly map;
+    private readonly nowMs;
+    private readonly sweepEvery;
+    private writes;
+    constructor(opts?: {
+        now?: () => number;
+        sweepEvery?: number;
+    });
+    /** Number of live entries currently held (after lazily ignoring nothing — counts raw map size). */
+    get size(): number;
+    private live;
+    /** Amortized O(1)/write: every SWEEP_EVERY writes, drop all expired entries so the map can't grow forever. */
+    private maybeSweep;
+    claim(key: string, ttlSec: number): Promise<ClaimResult>;
+    complete(key: string, result: StoredResult, ttlSec: number): Promise<void>;
+    fail(key: string): Promise<void>;
+}
+
+/**
+ * The normalized error envelope an executor returns. The HTTP STATUS is the real contract a sender's
+ * retry logic reads (2xx ack, 4xx permanent/no-retry, 5xx & 429 retry); the JSON body is for humans.
+ */
+interface ErrorEnvelope {
+    status: number;
+    code: string;
+    message: string;
+    retriable: boolean;
+}
+/**
+ * Throw this from a handler to fail with a specific code/retriability. `retriable` decides the status
+ * family ({@link toHttpStatus}) so the sender retries (5xx/429) or drops (4xx) correctly.
+ */
+declare class ExecutorError extends Error {
+    readonly code: string;
+    readonly retriable: boolean;
+    readonly httpStatus?: number;
+    constructor(args: {
+        code: string;
+        message: string;
+        retriable: boolean;
+        status?: number;
+    });
+    toEnvelope(): ErrorEnvelope;
+}
+/**
+ * Map an error to an HTTP status. An explicit `status` is honored when it agrees with `retriable`
+ * (5xx/429 for retriable, 4xx for permanent); otherwise the family default is used: retriable → 503,
+ * permanent → 400.
+ */
+declare function toHttpStatus(e: {
+    retriable: boolean;
+    httpStatus?: number;
+}): number;
+/** Serialize an envelope to a JSON body string. */
+declare function jsonResponseBody(env: ErrorEnvelope): string;
+
+export { type ClaimResult, type CreateExecutorOptions, DATA_HEADERS, type ErrorEnvelope, type Executor, type ExecutorContext, type ExecutorCredential, ExecutorError, type ExecutorHandler, type FetchCredentialOptions, type IdempotencyStore, MAX_SIG_ENTRIES, MemoryStore, type NodeReq, type NodeRes, type NormalizedRequest, type NormalizedResponse, SIGNING_SCHEME, type SignRequestInput, type SignedHeaders, type SignedParts, type StoredResult, type VerifyInput, type VerifyResult, buildCanonical, createExecutor, fetchExecutorCredential, jsonResponseBody, signRequest, toFetchHandler, toHttpStatus, toNodeHandler, unixSeconds, verify, verifySignatureHeader };