@layervai/qurl 0.3.1 → 0.5.0

package/dist/cjs/node/portal-opener.d.ts

@@ -0,0 +1,114 @@
+import type { NHPMessage } from "./nhp-wire.js";
+import { type PortalDeployment, type ValidatedCell, type ValidatedDeployment } from "./deployment.js";
+import { type NativeExchangeOptions } from "./native-udp.js";
+import { type VerifiedQv2Link } from "./qv2.js";
+export interface CreatePortalOpenerOptions {
+    /** Full qv2t1 qURL. The opener re-verifies it before each native open. */
+    readonly qurl: string;
+    /** Public deployment trust. Omit to load QURL_DEPLOYMENT on the first start. */
+    readonly deployment?: PortalDeployment;
+    /** Whole-operation deadline for each NHP open. The default is 15 seconds. */
+    readonly openTimeoutMs?: number;
+    /** Protected-content fetch implementation. Native NHP opening never uses it. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+export interface PortalStartOptions {
+    readonly signal?: AbortSignal;
+}
+/**
+ * Build one request for the exact target selected by `fetch` or
+ * `fetchDescendant`. The URL is a disposable copy; the opener pins the final
+ * request URL and Host to its SDK-owned target after this function returns.
+ */
+export type PortalRequestBuilder = (authenticatedTarget: URL) => RequestInit;
+export interface PortalFetchOptions {
+    /** Use `error` for signed requests whose method, target, timestamp, and nonce must not be replayed. */
+    readonly redirects?: "follow" | "error";
+}
+export type PortalOpenerState = "new" | "starting" | "ready" | "degraded" | "closed";
+export type PortalOpenerFailureClass = "" | "open_failed" | "target_changed";
+/** Secret-free, nonblocking lifecycle snapshot. */
+export interface PortalOpenerHealth {
+    readonly state: PortalOpenerState;
+    readonly ready: boolean;
+    readonly expiresAt?: Date;
+    readonly renewAt?: Date;
+    readonly lastOpenSucceededAt?: Date;
+    readonly lastFailureClass: PortalOpenerFailureClass;
+    readonly consecutiveFailures: number;
+}
+export interface PortalOpener {
+    /** Open now and schedule renewal before the admission expires. */
+    start(options?: PortalStartOptions): Promise<void>;
+    /** Start a fetch at the exact ACK URL. Same-origin redirects follow only when allowed. */
+    fetch(init?: RequestInit | PortalRequestBuilder, options?: PortalFetchOptions): Promise<Response>;
+    /**
+     * Start a fetch below the ACK URL. Each caller value is one raw path segment;
+     * the opener validates and escapes each segment before use. The ACK target's
+     * query is preserved.
+     */
+    fetchDescendant(pathSegments: readonly string[], init?: RequestInit | PortalRequestBuilder, options?: PortalFetchOptions): Promise<Response>;
+    /** Read local session state. This method does no I/O and exposes no capability. */
+    health(): PortalOpenerHealth;
+    /** Stop renewal and wipe mutable private-key, visitor-secret, and token buffers. */
+    close(): Promise<void>;
+}
+export declare class PortalConfigurationError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class PortalVerificationError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class PortalDenyError extends Error {
+    readonly errCode: string;
+    constructor(errCode: string);
+}
+export declare class PortalStateError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class PortalOpenerNotStartedError extends PortalStateError {
+    constructor();
+}
+export declare class PortalOpenerNotReadyError extends PortalStateError {
+    constructor(options?: ErrorOptions);
+}
+export declare class PortalOpenerClosedError extends PortalStateError {
+    constructor(options?: ErrorOptions);
+}
+export declare class PortalOpenTimeoutError extends PortalStateError {
+    constructor();
+}
+export declare class PortalTargetChangedError extends PortalStateError {
+    constructor();
+}
+export declare class PortalRedirectError extends PortalStateError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class PortalTooManyRedirectsError extends PortalStateError {
+    constructor();
+}
+export declare class PortalBusyError extends PortalStateError {
+    constructor();
+}
+export declare class PortalInvalidReplyError extends PortalStateError {
+    constructor(message: string, options?: ErrorOptions);
+}
+interface PortalRuntime {
+    readonly knock: (cell: ValidatedCell, key: Uint8Array, body: Uint8Array, options: NativeExchangeOptions) => Promise<NHPMessage>;
+    readonly fetch: typeof globalThis.fetch;
+    readonly nowNanos: () => bigint;
+    readonly nowEpochMs: () => number;
+    readonly setTimer: (callback: () => void, delayMs: number) => NodeJS.Timeout;
+    readonly clearTimer: (timer: NodeJS.Timeout) => void;
+    readonly setDeadlineTimer: (callback: () => void, delayMs: number) => NodeJS.Timeout;
+    readonly clearDeadlineTimer: (timer: NodeJS.Timeout) => void;
+}
+export declare function createPortalOpener(options: CreatePortalOpenerOptions): PortalOpener;
+export declare function createPortalOpenerWithRuntime(options: CreatePortalOpenerOptions, runtime: PortalRuntime): PortalOpener;
+declare function validatedCellForLink(link: VerifiedQv2Link, deployment: ValidatedDeployment): ValidatedCell;
+declare function validateSessionToken(value: string, decode?: (part: string) => Buffer): void;
+export declare const portalOpenerTesting: {
+    validatedCellForLink: typeof validatedCellForLink;
+    validateSessionToken: typeof validateSessionToken;
+};
+export {};