vouchly 0.0.0 → 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,365 @@
+import { CryptoKey, JWK, JWTPayload, ProtectedHeaderParameters } from "jose";
+//#region src/cache/hash.d.ts
+export declare function hashToken(token: string): Promise<string>;
+//#endregion
+//#region src/cache/types.d.ts
+type TokenCacheEntry = {
+  claims: JWTPayload;
+  /**
+   * Issuer.id, or the issuer's index in the verifier's list when it has no id.
+   */
+  issuer: string;
+  source: 'local' | 'remote';
+  /**
+   * The token header's `typ`, for a locally verified token that carried one.
+   */
+  typ?: string;
+  /**
+   * The token header's `alg`, for a locally verified token.
+   */
+  alg?: string;
+};
+interface ITokenCache {
+  get(key: string): Promise<TokenCacheEntry | undefined>;
+  /**
+   * @param ttl seconds; a value <= 0 stores nothing.
+   */
+  set(key: string, entry: TokenCacheEntry, ttl: number): Promise<void>;
+}
+type MemoryTokenCacheOptions = {
+  /**
+   * Maximum number of entries, default 10000.
+   */
+  max?: number;
+};
+//#endregion
+//#region src/cache/memory.d.ts
+type MemoryTokenCacheItem = {
+  entry: TokenCacheEntry;
+  expiresAt: number;
+};
+export declare class MemoryTokenCache implements ITokenCache {
+  protected max: number;
+  protected items: Map<string, MemoryTokenCacheItem>;
+  constructor(options?: MemoryTokenCacheOptions);
+  get(key: string): Promise<TokenCacheEntry | undefined>;
+  set(key: string, entry: TokenCacheEntry, ttl: number): Promise<void>;
+}
+//#endregion
+//#region src/discovery/types.d.ts
+type ProviderMetadata = {
+  issuer: string;
+  /**
+   * Required by the discovery key source, not by introspection.
+   */
+  jwks_uri?: string;
+  introspection_endpoint?: string;
+};
+type DiscoveryOptions = {
+  /**
+   * Seconds the provider metadata of an issuer is reused, default 600.
+   */
+  cacheMaxAge?: number;
+};
+//#endregion
+//#region src/discovery/module.d.ts
+/**
+ * Reads `<issuer>/.well-known/openid-configuration`. The issuer must come
+ * from configuration, never from a token. Answers are reused for
+ * cacheMaxAge seconds; after a failure, the issuer is not asked again for
+ * 30 seconds and calls fail fast instead.
+ */
+export declare function fetchProviderMetadata(issuer: string, fetchFn: typeof globalThis.fetch, options?: DiscoveryOptions): Promise<ProviderMetadata>;
+//#endregion
+//#region src/error/constants.d.ts
+export declare enum VouchlyErrorCode {
+  TOKEN_MALFORMED = "token_malformed",
+  TOKEN_EXPIRED = "token_expired",
+  TOKEN_INACTIVE = "token_inactive",
+  ISSUER_UNTRUSTED = "issuer_untrusted",
+  KEY_UNAVAILABLE = "key_unavailable",
+  SIGNATURE_INVALID = "signature_invalid",
+  CLAIM_INVALID = "claim_invalid",
+  INTROSPECTION_FAILED = "introspection_failed",
+  BINDING_MISMATCH = "binding_mismatch"
+}
+export declare const VOUCHLY_ERROR_MARKER: unique symbol;
+//#endregion
+//#region src/error/types.d.ts
+type VouchlyErrorOptions = {
+  cause?: unknown;
+  /**
+   * The HTTP status of a failed upstream answer, e.g. an introspection endpoint's.
+   */
+  status?: number;
+};
+//#endregion
+//#region src/error/module.d.ts
+export declare class VouchlyError extends Error {
+  readonly code: VouchlyErrorCode;
+  readonly status?: number;
+  readonly [VOUCHLY_ERROR_MARKER] = true;
+  constructor(code: VouchlyErrorCode, message?: string, options?: VouchlyErrorOptions);
+}
+export declare function isVouchlyError(input: unknown): input is VouchlyError;
+//#endregion
+//#region src/token/types.d.ts
+type ParsedToken = {
+  raw: string;
+  header: ProtectedHeaderParameters;
+  claims: JWTPayload;
+};
+//#endregion
+//#region src/token/module.d.ts
+export declare function isCompactToken(token: string): boolean;
+export declare function parseToken(token: string): ParsedToken;
+//#endregion
+//#region src/key/types.d.ts
+type KeySourceContext = {
+  token: ParsedToken;
+  issuer: Issuer;
+  fetch: typeof fetch;
+};
+type KeySource = (context: KeySourceContext) => Promise<CryptoKey | JWK>;
+type JWKSOptions = {
+  /**
+   * Milliseconds, see jose createRemoteJWKSet.
+   */
+  cacheMaxAge?: number;
+  /**
+   * Milliseconds, see jose createRemoteJWKSet.
+   */
+  cooldownDuration?: number;
+  /**
+   * Milliseconds, see jose createRemoteJWKSet.
+   */
+  timeoutDuration?: number;
+};
+type CachedKeysOptions = {
+  /**
+   * The cache key of the context; one load is shared per key.
+   */
+  key: (context: KeySourceContext) => string;
+  /**
+   * Seconds, default 300; 0 caches nothing.
+   */
+  ttl?: number;
+  /**
+   * Seconds, default 10, at most 2147483.
+   */
+  timeout?: number;
+  /**
+   * Maximum number of entries, default 100.
+   */
+  max?: number;
+};
+//#endregion
+//#region src/key/cached.d.ts
+export declare function cachedKeys(load: (context: KeySourceContext) => Promise<JWK>, options: CachedKeysOptions): KeySource;
+//#endregion
+//#region src/key/discovery.d.ts
+/**
+ * Resolves keys through the configured issuer's OIDC discovery document.
+ * A function issuer is refused: its only URL would be the token's own `iss`.
+ */
+export declare function discovery(options?: DiscoveryOptions): KeySource;
+//#endregion
+//#region src/key/jwks.d.ts
+export declare function jwks(url: string | URL, options?: JWKSOptions): KeySource;
+//#endregion
+//#region src/key/module.d.ts
+/**
+ * Resolves the key a token is verified with. Every failure, including a key
+ * the policy refuses, is a KEY_UNAVAILABLE VouchlyError.
+ */
+export declare function resolveVerificationKey(source: KeySource, context: KeySourceContext): Promise<CryptoKey>;
+//#endregion
+//#region src/key/static.d.ts
+export declare function staticKeys(keys: JWK[]): KeySource;
+//#endregion
+//#region src/issuer/types.d.ts
+type IntrospectionAuthorizationContext = {
+  /**
+   * true when the previous attempt was answered with 401.
+   */
+  retry: boolean;
+};
+type IntrospectionOptions = {
+  /**
+   * Default: the issuer's discovered introspection_endpoint.
+   */
+  endpoint?: string;
+  /**
+   * Client credentials (sent as HTTP Basic), or a function returning the
+   * whole Authorization header value. After a 401 a function is called
+   * again with `retry: true` and the request is repeated once.
+   */
+  authorization?: {
+    clientId: string;
+    clientSecret: string;
+  } | ((context: IntrospectionAuthorizationContext) => string | Promise<string>);
+  /**
+   * Upper bound, in seconds, for caching an introspection result.
+   */
+  maxCacheTTL?: number;
+};
+type Issuer = {
+  id?: string;
+  /**
+   * A string matches `iss` exactly. A function sees UNVERIFIED claims:
+   * it only selects this config and never replaces verification.
+   */
+  issuer: string | ((claims: JWTPayload) => boolean);
+  /**
+   * Default: discovery() when issuer is a string.
+   */
+  keys?: KeySource;
+  /**
+   * Default: 'local'.
+   */
+  verification?: 'local' | 'remote';
+  introspection?: IntrospectionOptions;
+  audience?: string | string[];
+  /**
+   * Default: the resolved key's algorithm only. A JWK without `alg` is
+   * imported with the token header's `alg`, restricted to what its key
+   * type supports; set this to pin the algorithm.
+   */
+  algorithms?: string[];
+  typ?: string;
+  /**
+   * Seconds, default 0.
+   */
+  clockTolerance?: number;
+  /**
+   * Default: ['exp'].
+   */
+  requiredClaims?: string[];
+  claims?: (claims: JWTPayload) => boolean | Promise<boolean>;
+};
+//#endregion
+//#region src/issuer/match.d.ts
+/**
+ * Whether an issuer config trusts a token by its UNVERIFIED claims. This only
+ * selects a config: verification still runs against it afterwards. A
+ * function matcher counts only when it returns exactly `true`; one that
+ * throws, or returns anything else (a Promise included), does not match.
+ */
+export declare function matchIssuer(issuer: Issuer, claims: JWTPayload): boolean;
+/**
+ * The index of the first issuer that trusts the claims, or -1.
+ */
+export declare function selectIssuer(issuers: Issuer[], claims: JWTPayload): number;
+//#endregion
+//#region src/introspection/module.d.ts
+/**
+ * RFC 7662: asks the issuer's introspection endpoint about a token and
+ * answers the response as its claims. Claim rules are the caller's.
+ */
+export declare function introspect(token: string, issuer: Issuer, fetchFn: typeof globalThis.fetch): Promise<JWTPayload>;
+//#endregion
+//#region src/introspection/types.d.ts
+type IntrospectionResponse = {
+  active: boolean;
+  [key: string]: unknown;
+};
+//#endregion
+//#region src/verifier/types.d.ts
+type VerifierOptions = {
+  issuers: Issuer[];
+  /**
+   * Default: a MemoryTokenCache; false disables caching.
+   */
+  cache?: ITokenCache | false;
+  /**
+   * Names the group of verifiers sharing a cache passed in; required then.
+   * Every verifier using one namespace must have the same issuer
+   * configuration, since a cache hit skips the key lookup and the
+   * signature check. Must not contain NUL. The cache key is the SHA-256 of
+   * the namespace, a NUL character and the token.
+   */
+  cacheNamespace?: string;
+  /**
+   * Default: the global fetch.
+   */
+  fetch?: typeof fetch;
+  /**
+   * The Issuer.id that introspects tokens which are not compact JWTs.
+   */
+  opaque?: string;
+};
+type VerifyOptions = {
+  /**
+   * The presented client certificate's SHA-256 thumbprint (base64url), for
+   * RFC 8705 bound tokens. A provider is only invoked for a bound token.
+   */
+  certificateThumbprint?: string | (() => string | undefined | Promise<string | undefined>);
+};
+type VerifyResult = {
+  claims: JWTPayload;
+  issuer: Issuer;
+  source: 'local' | 'remote';
+};
+interface IVerifier {
+  verify(token: string, options?: VerifyOptions): Promise<VerifyResult>;
+}
+//#endregion
+//#region src/verifier/binding.d.ts
+/**
+ * RFC 8705: a token carrying `cnf` is certificate-bound and fails closed
+ * unless the presented thumbprint equals `cnf.x5t#S256`. A `cnf` this check
+ * cannot satisfy (no `x5t#S256`, e.g. a DPoP `jkt`) fails too.
+ */
+export declare function assertCertificateBinding(claims: JWTPayload, thumbprint: string | undefined): void;
+//#endregion
+//#region src/verifier/module.d.ts
+type IssuerRecord = {
+  /**
+   * Issuer.id, or the issuer's index when it has none; the cache entry's issuer.
+   */
+  name: string;
+  issuer: Issuer;
+  keys?: KeySource;
+};
+export declare class Verifier implements IVerifier {
+  protected records: IssuerRecord[];
+  protected cache: ITokenCache | undefined;
+  protected fetch: typeof fetch;
+  protected opaque: IssuerRecord | undefined;
+  protected cacheNamespace: string;
+  constructor(options: VerifierOptions);
+  verify(token: string, options?: VerifyOptions): Promise<VerifyResult>;
+  /**
+   * The claim sets whose `cnf` a result must satisfy: an introspected
+   * compact token is held to its own `cnf` as well as the response's.
+   */
+  protected bindingClaims(claims: JWTPayload, source: VerifyResult['source'], token: ParsedToken | undefined): JWTPayload[];
+  protected selectRecord(token: ParsedToken): IssuerRecord;
+  protected verifyLocal(token: ParsedToken, record: IssuerRecord): Promise<JWTPayload>;
+  protected assertClaimsPredicate(issuer: Issuer, claims: JWTPayload): Promise<void>;
+  /**
+   * Verifies a token by RFC 7662 introspection and applies the issuer's
+   * audience and claims predicate to the response.
+   */
+  protected verifyIntrospection(token: string, record: IssuerRecord): Promise<JWTPayload>;
+  protected introspect(token: string, key: string, record: IssuerRecord, options: VerifyOptions, parsed?: ParsedToken): Promise<VerifyResult>;
+  /**
+   * A cache failure is a miss: the token is verified again instead. An entry
+   * is only served under the record an uncached verify would pick, and only
+   * after this verifier's own rules that need no signature passed on it:
+   * a verifier sharing the cache may have applied other ones.
+   */
+  protected readCache(key: string, token: ParsedToken | undefined): Promise<{
+    entry: TokenCacheEntry;
+    record: IssuerRecord;
+  } | undefined>;
+  /**
+   * Caches until `exp`, measured to the millisecond, or for at most `maxTTL` seconds when given. A token
+   * without `exp` is cached only under a `maxTTL`. A cache failure is ignored.
+   */
+  protected writeCache(key: string, entry: TokenCacheEntry, exp: unknown, maxTTL?: number): Promise<void>;
+}
+export declare function createVerifier(options: VerifierOptions): Verifier;
+//#endregion
+export type { CachedKeysOptions, DiscoveryOptions, ITokenCache, IVerifier, IntrospectionAuthorizationContext, IntrospectionOptions, IntrospectionResponse, Issuer, JWKSOptions, KeySource, KeySourceContext, MemoryTokenCacheOptions, ParsedToken, ProviderMetadata, TokenCacheEntry, VerifierOptions, VerifyOptions, VerifyResult, VouchlyErrorOptions };
+//# sourceMappingURL=index.d.mts.map