---
title: "openvibe-sdk/assertions · OpenVibe.Services"
canonical: "https://openvibe.services/docs/sdk/assertions"
updated: null
---

# openvibe-sdk/assertions · OpenVibe.Services

HTML: [openvibe-sdk/assertions · OpenVibe.Services](https://openvibe.services/docs/sdk/assertions)

# `openvibe-sdk/assertions`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

From `types/assertions.d.ts` (server only). Declarations are shown verbatim.

## 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;
~~~~