@pithy-sh/core 0.2.0 → 0.3.1

package/dist/http/oidcWebhook.d.ts

@@ -0,0 +1,283 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { MiddlewareHandler } from "hono";
+import { z } from "zod";
+import type { PithyHonoEnv } from "../capability/capability";
+/**
+ * The `signed-webhook` strategy for a sender that proves itself with an **OIDC token** rather than an HMAC.
+ * Issuers, key endpoint, audience and a claims predicate in; the verified claims, or a `PithyError`, out.
+ *
+ * Two mechanisms, one declared strategy. {@link ./verification.VerificationStrategy} already says as much —
+ * *"an HMAC, a signed JWS chain, an OIDC token… a rail whose sender proves it differently implements its
+ * own"* — so this sits beside {@link ./signedWebhook.requireSignedWebhook} and wears its seams, rather than
+ * adding a word to that union. What changes is where the proof comes from: with an HMAC both ends hold a
+ * secret, and with OIDC neither end holds anything. The sender asks its identity provider for a token that
+ * expires in minutes; the receiver asks the same provider for the public keys that check it.
+ *
+ * ## The claims check is the boundary, not the signature
+ *
+ * An identity provider signs tokens for **everybody** with the same handful of keys. GitHub signs one for
+ * every repository on the planet; Google signs one for every Pub/Sub push subscription. So a valid signature
+ * proves only *that provider minted this*, which any of their users can arrange in under a minute. What makes
+ * a token **ours** is what it claims: `aud`, which the sender names when it mints the token and which is the
+ * endpoint it was minted for, and whatever the {@link OidcWebhookScheme.claims} predicate asserts on top —
+ * `sub === "repo:pithy-sh/pithy:environment:npm-publish"` for a release job, an issuer's service account for
+ * a push subscription. Verify the signature, skip those, and the result is an endpoint every user of that
+ * provider can post to.
+ *
+ * That is why `claims` is a **predicate the route holds** rather than a value in configuration. It is the
+ * same constraint as a `ValueRotator`: the declaration is the `signed-webhook` tag on the route, and the code
+ * that decides who is allowed lives with the route, where it can be read beside the handler it protects.
+ *
+ * ## Four steps, in this order, and the order is the security property
+ *
+ * 1. **Pin the algorithm before touching a key.** `alg` arrives in a header nobody has verified yet, so it is
+ *    parsed against a literal `RS256` rather than looked up. That is what makes the two published confusions
+ *    unreachable — `none`, which asks for the signature to be skipped, and `HS256`, which asks the verifier to
+ *    HMAC with the *public* key as if it were a shared secret. Neither survives a literal.
+ * 2. **Resolve the key by `kid` from the issuer's published set.** Never from the token, which is why there is
+ *    no `jwk`/`x5u` handling here: a token that carries its own key is a token that verifies itself.
+ * 3. **Verify the signature over the exact received segments** — `header.claims` as encoded, never a
+ *    re-serialization. Key order and whitespace belong to the sender, not to us.
+ * 4. **Then read the claims,** and only then. A claim from an unverified token is a claim an attacker wrote,
+ *    so a verifier that reads `iss` or `sub` to decide *which key to fetch* has already trusted the forgery it
+ *    is about to check. Issuer, audience, expiry, and the caller's predicate are all after the signature.
+ *
+ * ## What a refusal says
+ *
+ * `core/webhook_unverified`, 401, one code for every step a sender can fail — unreadable token, unknown key,
+ * bad signature, wrong audience, expired, predicate false. The step goes in `detail`, which the HTTP codec
+ * strips, so an operator reading a log learns which check refused it and the sender learns only that
+ * something did. Values that decide something are named there (`kid`, `iss`, `aud`) because a misconfigured
+ * audience is the realistic failure and an operator cannot fix what the log will not name — truncated by
+ * {@link snippet}, and never the signature and never the whole token.
+ *
+ * Two failures are deliberately **not** the sender's. An endpoint with no issuers, no audience, no key
+ * endpoint, or a clock that is not a clock is a configuration fault and takes `core/internal` — reporting it
+ * as an unverified webhook sends an operator hunting a forger who is not there. And a key endpoint that
+ * cannot be reached or answers nonsense is `core/upstream_failed` (502), because a 500 tells an operator to
+ * read *our* logs and the thing that broke is the issuer's. Both still refuse the delivery: fail closed is
+ * about what happens to the request, not about whose code goes on it.
+ *
+ * ## What this proves, and what it does not
+ *
+ * The same caveat as the HMAC scheme, for the same reason: this proves a delivery is authentic and fresh,
+ * never that it is *new*. A captured token replays until it expires. A handler that grants, charges, or
+ * deletes needs its own uniqueness key.
+ */
+/** How long a fetched key set is reused. Issuers rotate slowly, and an unknown `kid` forces a refresh anyway. */
+export declare const OIDC_JWKS_TTL_SECONDS = 3600;
+/** Tolerance on `exp`, `nbf` and `iat`. A minute covers clock drift; an hour would cover a replay. */
+export declare const OIDC_CLOCK_SKEW_SECONDS = 60;
+/**
+ * The most tolerance this verifier accepts, and it refuses above rather than clamping.
+ *
+ * A skew is a replay window in the plainest possible units: every second of it is a second longer a captured
+ * token keeps working. Five minutes is the far end of real drift between two machines that both run NTP; past
+ * that a number has stopped covering drift and started covering a capture, which is what the sentence above
+ * says about an hour. Refused rather than clamped because a `604800` is a typo or a misunderstanding either
+ * way — clamped, it boots and nobody reads the line again; refused, it is a red boot and a two-character fix.
+ */
+export declare const OIDC_MAX_CLOCK_SKEW_SECONDS = 300;
+/**
+ * One published RSA verification key, in the shape a JWKS endpoint returns. `.loose()` because providers add
+ * fields, and a key set must not be rejected for carrying something this build does not read.
+ */
+export declare const OidcJwk: z.ZodObject<{
+    kid: z.ZodString;
+    kty: z.ZodString;
+    n: z.ZodString;
+    e: z.ZodString;
+    alg: z.ZodOptional<z.ZodString>;
+    use: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type OidcJwk = z.infer<typeof OidcJwk>;
+/** A published key set. At least one key: an empty set is an endpoint that is not answering properly. */
+export declare const OidcJwks: z.ZodObject<{
+    keys: z.ZodArray<z.ZodObject<{
+        kid: z.ZodString;
+        kty: z.ZodString;
+        n: z.ZodString;
+        e: z.ZodString;
+        alg: z.ZodOptional<z.ZodString>;
+        use: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type OidcJwks = z.infer<typeof OidcJwks>;
+/**
+ * The claims an OIDC token carries, narrowed to the ones that decide anything. `.loose()` keeps the rest —
+ * the predicate reads them, and a claim set must not be refused for being richer than expected.
+ *
+ * `aud` is a **string and only a string**, though RFC 7519 permits an array. The audience check is the
+ * boundary, and an array turns an equality into a set membership — one more shape for a verifier to be wrong
+ * about, on the check the whole scheme rests on. No sender the kit talks to mints one.
+ */
+export declare const OidcClaims: z.ZodObject<{
+    iss: z.ZodString;
+    aud: z.ZodString;
+    sub: z.ZodOptional<z.ZodString>;
+    exp: z.ZodNumber;
+    nbf: z.ZodOptional<z.ZodNumber>;
+    iat: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type OidcClaims = z.infer<typeof OidcClaims>;
+/** The response shape this module reads. Structural, so a test's transport need not be a whole `Response`. */
+export interface OidcJwksResponse {
+    /** Whether the status is 2xx. */
+    ok: boolean;
+    /** The status code, which is what decides the mapping. */
+    status: number;
+    /** The body as text. Read as text rather than JSON so a non-JSON answer is a diagnosis, not a throw. */
+    text(): Promise<string>;
+}
+/**
+ * The HTTP seam the key endpoint is reached through.
+ *
+ * Injectable for exactly one reason: **no test may reach a live identity provider**, and a verifier whose
+ * network call could not be substituted would have to be tested through a stub of itself, which proves
+ * nothing. One explicit parameter rather than a reassigned global — a global stub leaks between suites and
+ * hides which module was actually exercised.
+ */
+export type OidcJwksFetch = (url: string) => Promise<OidcJwksResponse>;
+/** The default transport: the runtime's own `fetch`. */
+export declare const oidcJwksFetch: OidcJwksFetch;
+/**
+ * Where a fetched key set is held between requests.
+ *
+ * **Injected, never a module global.** A cache in a module variable is one cache for the whole isolate that
+ * no caller owns, which is how `resetGoogleJwksCache` came to exist: once the state is unreachable, a test
+ * suite needs an exported function whose only purpose is to undo the previous suite. Passing the store in
+ * deletes that function and the class of bug it papers over — a test seeds its own, and a Worker gives one
+ * over KV or the Cache API and shares it across isolates.
+ *
+ * **Owning the store is not the same as having none.** {@link requireOidcWebhook} builds one per guard when a
+ * route gives none, because the guard is the surface anonymous traffic arrives on: with no cache, a 49-byte
+ * forged token naming a published `kid` buys a round trip to the issuer, 1:1, until the issuer rate-limits us
+ * and the real deliveries 502 alongside the forgeries. {@link verifyOidcToken} called directly is the other
+ * case and does fetch per call — its caller holds one token it has already decided to check, so there is no
+ * flood to absorb and no cache to acquire by surprise.
+ *
+ * Public keys, so nothing here is what CLAUDE.md's secrets rule governs: the whole point of a JWKS endpoint
+ * is that anyone may read it. What the cache buys is one round trip per TTL instead of one per delivery.
+ */
+export interface JwksCache {
+    /** The key set held for `url`, or `undefined` when nothing usable is held. */
+    get(url: string): Promise<readonly OidcJwk[] | undefined>;
+    /** Hold a freshly fetched key set for `url` for `ttlSeconds`. */
+    set(url: string, keys: readonly OidcJwk[], ttlSeconds: number): Promise<void>;
+}
+/**
+ * A key cache in memory, expiring on a clock the caller owns.
+ *
+ * One object per call, so two callers never share one by accident and a test's cache dies with its test. The
+ * clock is injected for the same reason it is everywhere else here: an expiry that depends on wall time is an
+ * assertion nobody can write.
+ */
+export declare function memoryJwksCache(options?: {
+    now?: () => Date;
+}): JwksCache;
+/** What the two ends of the scheme must agree on, and what the receiver decides for itself. */
+export interface OidcWebhookScheme {
+    /**
+     * The `iss` values this endpoint accepts. More than one only where a provider publishes more than one
+     * spelling of itself — Google issues under both `accounts.google.com` and `https://accounts.google.com`;
+     * GitHub uses one. Empty is a configuration fault, never "accept anything".
+     */
+    issuers: readonly string[];
+    /** Where the issuer publishes the keys that sign its tokens. Public, so it is configuration and not a secret. */
+    jwksUrl: string;
+    /** The `aud` the token must claim — the value the sender named when it minted one. The real boundary. */
+    audience: string;
+    /**
+     * Whatever else makes a token *this endpoint's*: `(claims) => claims.sub === "repo:owner/name:environment:x"`.
+     *
+     * A predicate rather than configuration, because it cannot cross into `pithy.manifest.json` and should not
+     * try: the manifest declares the strategy, the route holds the rule. Run **last**, after the signature and
+     * every standard claim, so it is only ever handed claims that are already proven to be the issuer's.
+     */
+    claims: (claims: OidcClaims) => boolean | Promise<boolean>;
+    /**
+     * Tolerance on `exp`, `nbf` and `iat`, in seconds. Defaults to {@link OIDC_CLOCK_SKEW_SECONDS} and must be
+     * a finite number from 0 to {@link OIDC_MAX_CLOCK_SKEW_SECONDS}; anything else is `core/internal`, because
+     * this is the second operand of all three freshness comparisons and one `NaN` disables them together.
+     */
+    skewSeconds?: number;
+    /**
+     * How long a fetched key set is held. Defaults to {@link OIDC_JWKS_TTL_SECONDS} and must be a finite number
+     * of seconds — a `NaN` is an entry that never expires, which pins a key the issuer has rotated out.
+     */
+    jwksTtlSeconds?: number;
+    /**
+     * Where fetched keys are held between deliveries. Never a module global: {@link requireOidcWebhook} builds
+     * one per guard when a route gives none, and {@link verifyOidcToken} called directly fetches per call.
+     */
+    jwksCache?: JwksCache;
+    /** The HTTP seam the key endpoint is reached through. Defaults to the runtime's `fetch`. */
+    transport?: OidcJwksFetch;
+}
+/** Everything {@link verifyOidcToken} needs beyond the token itself. */
+export interface VerifyOidcTokenOptions extends OidcWebhookScheme {
+    /** The clock. Injectable so an expiry refusal is deterministic rather than wall-clock dependent. */
+    now?: Date;
+}
+/** Everything {@link requireOidcWebhook} needs, as a route wears it. */
+export interface OidcWebhookGuardOptions extends OidcWebhookScheme {
+    /** The header the token arrives in, lower case. Defaults to `authorization`, carrying `Bearer <token>`. */
+    header?: string;
+    /** The clock, for the freshness checks. A function because a guard is built once and used per request. */
+    now?: () => Date;
+}
+/**
+ * Verify one OIDC token and return its claims. Throws, never reports.
+ *
+ * The steps run in the order the module doc gives, and that order **is** the security property: algorithm
+ * pinned, key resolved by `kid` from the published set, signature checked over the received bytes, and only
+ * then a single claim read. A verifier that reads a claim to decide which key to fetch has trusted the thing
+ * it has not checked yet.
+ *
+ * @throws {@link WebhookUnverifiedError} (401) when the sender did not prove itself — unreadable token,
+ *   unknown key, bad signature, wrong issuer or audience, expired, not yet valid, predicate false.
+ * @throws {@link InternalError} (500) when this endpoint is not configured to verify anything.
+ * @throws {@link UpstreamError} (502) when the issuer's key endpoint could not be read.
+ */
+export declare function verifyOidcToken(token: string, options: VerifyOidcTokenOptions): Promise<OidcClaims>;
+/**
+ * The OIDC gate, as a route wears it: `app.post(path, requireOidcWebhook({…}), zValidator("json", Body,
+ * validationHook), handler)`.
+ *
+ * ## Why the header is read before anything else
+ *
+ * The bearer header is the cheapest thing to check and the commonest thing to be missing, so it goes first. A
+ * delivery carrying no token is refused whatever the body holds, and fetching a key set before looking would
+ * be unauthenticated work an anonymous POST could buy on the one route whose purpose is to refuse anonymous
+ * callers.
+ *
+ * ## Why a cache is not optional here
+ *
+ * A caller that presents *something* is past that first check, and the next thing the verifier needs is the
+ * issuer's key set. So the guard builds a {@link memoryJwksCache} when the route gives none — once, when the
+ * middleware is constructed, never per request, which is a cache that has never held anything. A `kid` is
+ * published by definition, which makes a 49-byte token naming one the cheapest thing on the internet to send,
+ * and with no cache each one is a round trip to the issuer, 1:1. That is a bandwidth multiplier aimed at
+ * somebody else's endpoint, and once the issuer rate-limits us {@link fetchJwks} maps it to
+ * `core/upstream_failed` for the genuine deliveries too — an anonymous caller taking the boundary down by
+ * asking it politely. A route wanting a harder bound (shared across isolates, or rate-limiting) passes its
+ * own {@link OidcWebhookScheme.jwksCache}, and this one is never built.
+ *
+ * A `kid` **nobody** publishes still costs one fetch per delivery, cache or no cache, because an unknown key
+ * id is how rotation announces itself and declining to look is an outage. That bound is per delivery and
+ * lives in {@link resolveKey}; the cache is what collapses the other flood, the one naming a key that exists.
+ *
+ * ## Why nothing is published to the request
+ *
+ * The gate proves the caller and returns; it sets no request variable. The claims a route cares about are the
+ * ones its own {@link OidcWebhookScheme.claims} predicate already asserted, and a handler that needs the
+ * whole claim set calls {@link verifyOidcToken} directly rather than reading a variable it must remember to
+ * null-check.
+ *
+ * The body is never read here — unlike the HMAC gate, whose proof covers the bytes. An OIDC token proves who
+ * sent the request and says nothing about what they sent, so the route's `zValidator` is the only thing that
+ * touches the body, and it sees an untouched stream.
+ */
+export declare function requireOidcWebhook(options: OidcWebhookGuardOptions): MiddlewareHandler<PithyHonoEnv>;
+//# sourceMappingURL=oidcWebhook.d.ts.map

package/dist/http/oidcWebhook.d.ts.map

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