@stacksjs/router/dist/signed-url.d.ts

The Stacks framework router.

import type { EnhancedRequest } from '@stacksjs/bun-router';
/**
 * Sign an existing URL (full or path-only). Returns a new URL string
 * with `expires` (optional) and `signature` query params appended.
 *
 * Path-only inputs (`/api/email/verify?user=42`) inherit `APP_URL` as
 * the origin — same convention as {@link buildUrl}.
 */
export declare function signUrl(input: string, options?: SignedUrlOptions): string;
/**
 * Convenience wrapper that resolves a named route to a URL via {@link buildUrl}
 * and then signs it. Mirrors Laravel's `URL::signedRoute()`.
 *
 * @example
 * ```ts
 * route.get('/api/email/verify', VerifyEmailAction).name('email.verify')
 * const link = signedUrl('email.verify', { user: 42 }, { ttl: 60 * 60 * 24 })
 * // → https://app.example.com/api/email/verify?user=42&expires=1716470400&signature=…
 * ```
 */
export declare function signedUrl(routeName: string, params?: Record<string, string | number>, options?: SignedUrlOptions): string;
/**
 * Verify the `signature` (and optional `expires`) on an incoming URL.
 * Returns a discriminated result so callers can pick their own status
 * code per failure mode.
 */
export declare function verifySignedUrl(input: string | URL): SignedUrlVerifyResult;
/**
 * Middleware shape for `route.middleware('signed')`. Verifies the
 * incoming URL's signature and throws a `Response` (the router's
 * short-circuit contract) when it fails. Drop in as a route-level
 * middleware on any URL minted by {@link signedUrl}.
 *
 * @example
 * ```ts
 * route.get('/email/verify', 'Actions/VerifyEmail').middleware('signed')
 * ```
 */
export declare function verifySignedUrlMiddleware(req: EnhancedRequest): Promise<void>;
export declare interface SignedUrlOptions {
  expiresAt?: number
  ttl?: number
}
/**
 * Result of {@link verifySignedUrl}. The `reason` only fires when `valid`
 * is `false` — gives callers (and middleware) enough to decide whether
 * to log, return 401, or return 410 (expired vs. tampered).
 */
export type SignedUrlVerifyResult = | { valid: true }
  | { valid: false, reason: 'missing-signature' | 'expired' | 'invalid-signature' }