openvibe-sdk/assertions

interface SubjectAssertionClaims

The claims of a subject assertion (ADR-003, the 2026-11-06 amendment; plan H1).

export interface SubjectAssertionClaims {
    /** The Network issuer. */
    iss: string;
    /** The person: usr_… */
    sub: string;
    /** The service the assertion is for (openvibe.billing). */
    aud: string | string[];
    /** The service the assertion was minted for (svc:live). */
    act?: string;
    /** Unique per assertion; a replayed one is refused. */
    jti: string;
    iat: number;
    exp: number;
    nbf?: number;
}

type SubjectAssertionResult

export type SubjectAssertionResult = { ok: true; claims: SubjectAssertionClaims } | { ok: false; code: string; reason: string };

interface RequestSubjectAssertionOptions

export interface RequestSubjectAssertionOptions {
    /** The person's own Network access token (their session). Without it Network signs nothing. */
    userToken: string;
    /** The service the assertion is for (openvibe.billing), or a list when it travels a chain. */
    audience: string | string[];
    /** The services that may carry it (the minting service is always in it). */
    for?: string | string[];
    /** Where Network lives (public URL). */
    network?: string;
    /** Where Network's /internal lives (loopback, same host). */
    internalUrl?: string;
    /** The whole endpoint, when it is neither of the two above. */
    url?: string;
    /** The caller's own service token (Bearer). */
    token?: string;
    /** Or a client with getToken() (the SDK's createServiceTokenClient). */
    tokenClient?: { getToken(ctx?: { audience?: string; scope?: string }): Promise<string> };
    /** The person the caller says it acts for; Network checks it against the token. */
    subject?: string;
    fetch?: FetchLike;
    timeoutMs?: number;
    log?: JwksClientOptions['log'];
}

interface SubjectAssertion

export interface SubjectAssertion {
    /** The signed JWT, to be sent as X-OV-Subject-Assertion. */
    assertion: string;
    /** The person the assertion names. */
    subject: string | null;
    audience: string | string[];
    jti: string | null;
    expires_at: string | null;
    expires_in: number;
}

function requestSubjectAssertion

Ask Network to sign the person's own token into an assertion for one audience.

export declare function requestSubjectAssertion(opts: RequestSubjectAssertionOptions): Promise<SubjectAssertion>;

interface VerifySubjectAssertionOptions

export interface VerifySubjectAssertionOptions {
    /** Network's JWKS (a URL, a document or a client), or the EC public key. */
    jwks?: { keys?: object[]; public_key?: string } | string | JwksClient;
    publicKey?: string | object;
    /** The audience this service answers for (openvibe.billing). */
    audience?: string | string[];
    issuer?: string;
    /** The service presenting the assertion (svc:live): it must be one the assertion names. */
    caller?: string;
    clockSkewSec?: number;
    now?: number;
    /** A Map or Set of jtis already used: a replay is refused. */
    seen?: Set<string> | Map<string, number> | { has(jti: string): boolean };
    log?: JwksClientOptions['log'];
}

function verifySubjectAssertion

Check a subject assertion: signature, audience, expiry, the service it was minted for, the jti.

export declare function verifySubjectAssertion(assertion: string, opts?: VerifySubjectAssertionOptions): Promise<SubjectAssertionResult>;

interface SubjectAssertionVerifier

export interface SubjectAssertionVerifier {
    verify(assertion: string, opts?: { caller?: string; seen?: Set<string> | Map<string, number> | { has(jti: string): boolean } }): Promise<SubjectAssertionResult>;
    /** How many jtis are remembered (the replay window). */
    size(): number;
}

function createSubjectAssertionVerifier

A verifier that remembers the jtis it has seen, so a replayed assertion is refused.

export declare function createSubjectAssertionVerifier(opts: { jwks?: VerifySubjectAssertionOptions['jwks']; audience?: string | string[]; issuer?: string; clockSkewSec?: number; replayWindowMs?: number; log?: JwksClientOptions['log'] }): SubjectAssertionVerifier;

function subjectAssertionHeader

The header a money call carries the assertion in.

export declare function subjectAssertionHeader(assertion: string): { 'x-ov-subject-assertion': string };

interface SubjectAssertionMinterOptions

export interface SubjectAssertionMinterOptions {
    /** Where Network lives (public URL). */
    network?: string | { internalUrl?: string; url?: string };
    /** Where Network's /internal lives (loopback, same host). */
    internalUrl?: string;
    /** The whole endpoint, when it is neither of the two above. */
    url?: string;
    /** The caller's own OAuth client: the service token it presents to Network. */
    oauth?: { clientId?: string; clientSecret?: string };
    /** The audience of that service token (openvibe.network). */
    audience?: string;
    scope?: string | string[];
    fetch?: FetchLike;
    timeoutMs?: number;
    log?: JwksClientOptions['log'];
}

interface SubjectAssertionMinter

export interface SubjectAssertionMinter {
    /** The assertion for a person, or null when it cannot be had (never throws). */
    mint(opts: { userToken?: string | null; subject?: string; audience: string | string[]; for?: string | string[] }): Promise<string | null>;
    /** Where the assertions are asked for. */
    endpoint: string;
}

function createSubjectAssertionMinter

The caller's own minter: ask Network to sign the person's token into an assertion.

export declare function createSubjectAssertionMinter(opts?: SubjectAssertionMinterOptions): SubjectAssertionMinter;

const ASSERTION_HEADER

The header a money call carries the assertion in.

export declare const ASSERTION_HEADER: string;

const ASSERTION_TTL_S

How long an assertion lives (seconds).

export declare const ASSERTION_TTL_S: number;

const REPLAY_WINDOW_MS

The default replay window (milliseconds).

export declare const REPLAY_WINDOW_MS: number;

const CLOCK_SKEW_SEC

How much clock difference is forgiven (seconds).

export declare const CLOCK_SKEW_SEC: number;