API index and search · Build metadata

Supporting declarations

packages/affinity/src/index.ts. These declarations explain referenced types. Only package-page symbols are package exports.

Exact source

/** The token namespace marker — the first dot-segment of every ticket. */
export declare const TICKET_PREFIX = "aff";

/** The base ws subprotocol offered alongside the `aff.*` ticket; the daemon echoes it on the 101. */
export declare const WS_SUBPROTOCOL = "rindle.v1";

/** The api-server → fleet control-plane header carrying the ticket on `/materialize` and `/query`. */
export declare const HEADER_NAME = "Rindle-Affinity";

/**
 * The signed ticket body. Field order here is the canonical mint order — it is exactly the compact
 * JSON that gets base64url-encoded and signed, so it must match the Rust `Payload` struct order.
 */
export interface Payload {
    /** App id the ticket is scoped to. */
    app: string;
    /** Placement target id. */
    mid: string;
    /** Region code of `mid`. */
    region: string;
    /** Subject: the connection identity (clientInstanceId). */
    sub: string;
    /** Issued-at, unix seconds (informational). */
    iat: number;
    /** Expiry, unix seconds. `verify` rejects once `now > exp`. */
    exp: number;
    /** Generation minted under; a fleet-wide bump drains older tickets. */
    gen: number;
}

/** What {@link verify} holds a ticket against, supplied by the verifier. */
export interface Expect {
    /** The verifier's app id; must equal `payload.app`. */
    app: string;
    /** Current wall-clock, unix seconds. `exp < now` ⇒ rejected. */
    now: number;
    /** Minimum accepted generation; `gen < minGen` ⇒ rejected. `0` accepts any. */
    minGen: number;
}

/** Why a ticket failed {@link verify}. Every variant is a terminal reject (fall back to re-pin). */
export type VerifyError = "malformed" | "bad-signature" | "wrong-app" | "expired" | "stale-generation";

/** {@link verify}'s result: the authenticated payload, or a reason. */
export type VerifyResult = {
    readonly ok: true;
    readonly payload: Payload;
} | {
    readonly ok: false;
    readonly error: VerifyError;
};

type Key = string | Uint8Array;

/**
 * Mint a ticket over `payload`, signed with `key`. Deterministic (no randomness): the same
 * `(payload, key)` always yields the same token. The compact JSON is built in the fixed field order
 * so the bytes match the Rust crate's `serde_json` compact output.
 */
export declare function mint(payload: Payload, key: Key): string;

/**
 * Verify `token` against `keys` (current first, then rotation-window predecessors) and `expect`.
 * The HMAC is checked (constant-time) over the transmitted base64url payload segment before the
 * payload is parsed, so a tampered payload fails as `bad-signature`, never as a parse of attacker
 * bytes.
 */
export declare function verify(token: string, keys: readonly Key[], expect: Expect): VerifyResult;

/**
 * Extract the `aff.*` ticket from a `Sec-WebSocket-Protocol` header value (a comma list, e.g.
 * `rindle.v1, aff.<…>`). Returns the raw ticket segment for {@link verify}, or `null`. Does not verify.
 */
export declare function wsSubprotocolTicket(header: string): string | null;

/** Whether the header offers the base {@link WS_SUBPROTOCOL} — the daemon must echo it on the 101. */
export declare function wsOffersBase(header: string): boolean;

/** Extract the ticket from a {@link HEADER_NAME} value. Returns the raw segment, or `null`. */
export declare function headerTicket(value: string): string | null;