@rindle/affinity

0.0.0 · Public export map; development manifest version (0.0.0).

Source revision 05d0bf2c2e56 · build details

Source revision: 05d0bf2c2e56.
TypeScript input SHA-256: aabe6cfcc4172b870d5e272142958e9ea8d8784c2aa23133156e5a7ee633318e
Generated 2026-09-04T23:58:25.590Z with TypeScript 6.0.3. Public TypeScript checks and declaration emit passed. Package runtime tests are separate.

Entry point source

Expect

InterfaceDeclaration · Source: packages/affinity/src/index.ts:50 · Supporting declarations

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;
}

HEADER_NAME

VariableDeclaration · Source: packages/affinity/src/index.ts:26 · Supporting declarations

The api-server → fleet control-plane header carrying the ticket on /materialize and /query.

export declare const HEADER_NAME = "Rindle-Affinity";

headerTicket

FunctionDeclaration · Source: packages/affinity/src/index.ts:150 · Supporting declarations

Extract the ticket from a {@link HEADER_NAME} value. Returns the raw segment, or null.

export declare function headerTicket(value: string): string | null;

mint

FunctionDeclaration · Source: packages/affinity/src/index.ts:89 · Supporting declarations

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;

Payload

InterfaceDeclaration · Source: packages/affinity/src/index.ts:32 · Supporting declarations

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;
}

TICKET_PREFIX

VariableDeclaration · Source: packages/affinity/src/index.ts:20 · Supporting declarations

The token namespace marker — the first dot-segment of every ticket.

export declare const TICKET_PREFIX = "aff";

verify

FunctionDeclaration · Source: packages/affinity/src/index.ts:110 · Supporting declarations

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;

VerifyError

TypeAliasDeclaration · Source: packages/affinity/src/index.ts:60 · Supporting declarations

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";

VerifyResult

TypeAliasDeclaration · Source: packages/affinity/src/index.ts:68 · Supporting declarations

{@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;
};

WS_SUBPROTOCOL

VariableDeclaration · Source: packages/affinity/src/index.ts:23 · Supporting declarations

The base ws subprotocol offered alongside the aff.* ticket; the daemon echoes it on the 101.

export declare const WS_SUBPROTOCOL = "rindle.v1";

wsOffersBase

FunctionDeclaration · Source: packages/affinity/src/index.ts:145 · Supporting declarations

Whether the header offers the base {@link WS_SUBPROTOCOL} — the daemon must echo it on the 101.

export declare function wsOffersBase(header: string): boolean;

wsSubprotocolTicket

FunctionDeclaration · Source: packages/affinity/src/index.ts:136 · Supporting declarations

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;