OAuthServer

Class: OAuthServer<T>

Defined in: packages/oauth/src/oauthserver.service.ts:236

OAuth 2.1 authorization server issuing scoped TokenService tokens to native and MCP clients

Routes:

GET /.well-known/oauth-authorization-server: server metadata (RFC 8414)
GET <url>/authorize: authorization endpoint (code flow, PKCE S256 only)
POST <url>/token: token endpoint (authorization code, refresh token and device code grants)
POST <url>/revoke: revocation endpoint (RFC 7009)
POST <url>/device_authorization: device authorization endpoint (RFC 8628)

Browser operations (browser session, pending request cookie), hidden from the transports and served on routes of their own below url, the path of the pending request cookie, whatever transports are configured:

GET <url>/consent/request: OAuth.Consent.Get
POST <url>/consent/decide: OAuth.Consent.Decide
POST <url>/device/lookup: OAuth.Device.Lookup

Connected apps operations (logged-in user, own records only): OAuth.Sessions, OAuth.Grants, OAuth.Revoke, OAuth.Forget

Webda Modda

OAuthServer

Extends

Service<T>

Type Parameters

T

T extends OAuthServerParameters = OAuthServerParameters

Constructors

Constructor

new OAuthServer<T>(name, params): OAuthServer<T>

Defined in: packages/core/lib/services/service.d.ts:72

Service

Parameters

name

string

The name of the service

params

T

The parameters block define in the configuration file

Returns

OAuthServer<T>

Inherited from

Service<T>.constructor

Properties

_compiledCapabilities

protected _compiledCapabilities: Record<string, any>

Defined in: packages/core/lib/services/iservice.d.ts:38

Capabilities detected at compile-time from @WebdaCapability-tagged interfaces.

Populated during Service.resolve by reading the service's entry in webda.module.json. Each key is a capability name (e.g., "request-filter"), and the value is an empty object {} by default. Override getCapabilities to provide capability-specific configuration or to conditionally disable capabilities.

See

getCapabilities

Inherited from

Service._compiledCapabilities

[WEBDA_EVENTS]

[WEBDA_EVENTS]: object

Defined in: packages/core/lib/services/service.d.ts:50

Set the Webda events here

Inherited from

Service.[WEBDA_EVENTS]

clients

clients: ClientRegistry

Defined in: packages/oauth/src/oauthserver.service.ts:238

Client resolution

deviceRequests

deviceRequests: Map<string, number[]>

Defined in: packages/oauth/src/oauthserver.service.ts:246

Times of the recent device authorization requests, by ip:<client ip>

logger

protected logger: Logger

Defined in: packages/core/lib/services/service.d.ts:59

Logger with class context

Inherited from

Service.logger

lookupFailures

lookupFailures: Map<string, number[]>

Defined in: packages/oauth/src/oauthserver.service.ts:244

Times of the recent failed device lookups, by session:<uuid> and ip:<client ip>

metrics?

protected optional metrics?: object

Defined in: packages/core/lib/services/service.d.ts:63

Get metrics

Inherited from

Service.metrics

name

readonly name: string

Defined in: packages/core/lib/services/iservice.d.ts:18

Inherited from

Service.name

parameters

readonly parameters: T

Defined in: packages/core/lib/services/iservice.d.ts:19

Inherited from

Service.parameters

registrationRequests

registrationRequests: Map<string, number[]>

Defined in: packages/oauth/src/oauthserver.service.ts:248

Times of the recent client registrations, by ip:<client ip>

sweeping?

protected optional sweeping?: Promise<number>

Defined in: packages/oauth/src/oauthserver.service.ts:242

Sweep in progress: a new sweep joins it

sweepTimer?

protected optional sweepTimer?: Timeout

Defined in: packages/oauth/src/oauthserver.service.ts:240

Periodic sweep of the expired OAuth records

createConfiguration?

static optional createConfiguration?: (params) => any

Defined in: packages/core/lib/services/iservice.d.ts:23

Create configuration set by the application on load

Parameters

params

any

Returns

any

Inherited from

Service.createConfiguration

filterConfiguration?

static optional filterConfiguration?: (params) => any

Defined in: packages/core/lib/services/iservice.d.ts:27

Create configuration set by the application on load

Parameters

params

any

Returns

any

Inherited from

Service.filterConfiguration

Parameters

static Parameters: typeof ServiceParameters

Defined in: packages/core/lib/services/service.d.ts:46

Service parameters

Inherited from

Service.Parameters

Methods

__clean()

abstract __clean(): Promise<void>

Defined in: packages/core/lib/services/service.d.ts:215

Clean the service data, can only be used in test mode

Returns

Promise<void>

Inherited from

Service.__clean

accessFamily()

protected accessFamily(token, clientId, issuer): Promise<string | undefined>

Defined in: packages/oauth/src/oauthserver.service.ts:1537

Parameters

token

string

presented token

clientId

string

authenticated client

issuer

string

issuer, origin of the protected resources

Returns

Promise<string | undefined>

the family of the access token, when it is a valid one issued to the client, bound to no resource or to a registered one

accessTtl()

protected accessTtl(): number

Defined in: packages/oauth/src/oauthserver.service.ts:402

Returns

number

lifetime of the issued access tokens (s)

addListener()

addListener<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:80

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void | Promise<void>

the event listener

Returns

this

this for chaining

See

EventEmitter.addListener

Inherited from

Service.addListener

addRoute()

protected addRoute(url, methods, executer, openapi?, override?): void

Defined in: packages/core/lib/services/service.d.ts:177

Add a route dynamicaly

Parameters

url

string

of the route can contains dynamic part like {uuid}

methods

HttpMethodType[]

the HTTP methods

executer

Function

Method to execute for this route

openapi?

OpenAPIWebdaDefinition

the OpenAPI specification

override?

boolean

whether to override existing

Returns

void

Inherited from

Service.addRoute

approveCode()

protected approveCode(ctx, pending, scope): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1001

Issue an authorization code for an approved request and redirect to the client

Parameters

ctx

WebContext

web context

pending

PendingRequest

pending request

scope

Scope

granted scope

Returns

Promise<void>

approveDevice()

protected approveDevice(pending, identity, scope): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1045

Approve a pending device authorization: compare-and-set of its status from pending, so a code is decided once

Parameters

pending

PendingRequest

pending request

identity

GrantIdentity

identity of the user

scope

Scope

granted scope

Returns

Promise<void>

Throws

BadRequest when the device code is gone, expired or already decided

authorize()

authorize(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:593

Authorization endpoint: validate the request, keep it in the pending cookie and send the browser to the login or the consent page.

Errors before the client and its redirect_uri are validated render an error page and never redirect

Parameters

ctx

WebContext

web context

Returns

Promise<void>

once the response is written

authorizeClientEvent()

authorizeClientEvent(_event, _context): boolean

Defined in: packages/core/lib/services/service.d.ts:153

Authorize a public event subscription

Parameters

_event

string

the event name

_context

OperationContext

the execution context

Returns

boolean

true if the condition is met

Inherited from

Service.authorizeClientEvent

browserOperation()

protected browserOperation(ctx, operationId): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1133

Serve a browser operation on its route: called through core, so input validation and the operation authorizers apply as on any transport

Parameters

ctx

WebContext

web context

operationId

string

operation

Returns

Promise<void>

callableOperations()

protected callableOperations(ctx, requested): Promise<string[]>

Defined in: packages/oauth/src/oauthserver.service.ts:952

Parameters

ctx

WebContext

web context of the user

requested

Scope

requested scope

Returns

Promise<string[]>

the requested operations the user can call, in registration order

cleanHostname()

protected cleanHostname(hostname): string | undefined

Defined in: packages/oauth/src/oauthserver.service.ts:757

Parameters

hostname

string | undefined

untrusted hostname shown on the consent page

Returns

string | undefined

the hostname without control or format (bidi, zero-width) characters, capped; undefined when empty

clearPending()

protected clearPending(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:943

Parameters

ctx

WebContext

web context

Returns

Promise<void>

codeRedirect()

protected codeRedirect(pending, identity, scope): Promise<string>

Defined in: packages/oauth/src/oauthserver.service.ts:990

Parameters

pending

PendingRequest

approved request

identity

GrantIdentity

identity of the user

scope

Scope

granted scope

Returns

Promise<string>

the client redirect carrying a new authorization code

codeReused()

protected codeReused(ref): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1318

A used code was presented again: mark it, then revoke the family issued from it once recorded. The exchange that records the family checks the mark afterwards, so the family is revoked whichever runs first

Parameters

ref

ModelRefWithCreate<Storable<any, any>>

code reference

Returns

Promise<void>

computeParameters()

computeParameters(): void

Defined in: packages/core/lib/services/service.d.ts:77

Used to compute or derivate input parameter to attribute

Returns

void

Deprecated

Inherited from

Service.computeParameters

connectedAppsUser()

protected connectedAppsUser(): string

Defined in: packages/oauth/src/oauthserver.service.ts:1548

Returns

string

the user managing their connected apps

Throws

Unauthorized without a logged-in session, or with a delegated (scoped) token

consentDecide()

consentDecide(allow, operations, csrf, remember?): Promise<{ redirect: string; }>

Defined in: packages/oauth/src/oauthserver.service.ts:856

Record the user's decision on the pending request

Parameters

allow

boolean

grant or deny

operations

string[]

selected operation ids

csrf

string

token from OAuth.Consent.Get

remember?

boolean

remember the consent for this client

Returns

Promise<{ redirect: string; }>

where the browser goes next

consentGet()

consentGet(): Promise<ConsentRequest>

Defined in: packages/oauth/src/oauthserver.service.ts:770

Pending consent request of the browser

Returns

Promise<ConsentRequest>

the request to display

consentPage()

consentPage(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1868

Built-in consent page: renders OAuth.Consent.Get, sends OAuth.Consent.Decide

Parameters

ctx

WebContext

web context

Returns

Promise<void>

countAttempts()

protected countAttempts(attempts, key, now, window?): number

Defined in: packages/oauth/src/oauthserver.service.ts:1800

Parameters

attempts

Map<string, number[]>

rate limit state

key

string

rate limit key

now

number

current time

window?

number = LOOKUP_WINDOW

window (ms)

Returns

number

attempts of the key in the window

countLookupFailures()

protected countLookupFailures(key, now): number

Defined in: packages/oauth/src/oauthserver.service.ts:1789

Parameters

key

string

rate limit key

now

number

current time

Returns

number

failed lookups of the key in the window

createDeviceCode()

protected createDeviceCode(data): Promise<string>

Defined in: packages/oauth/src/oauthserver.service.ts:1717

Store a device code under a free user code: a drawn code already taken is drawn again, a bounded number of times

Parameters

data

Omit<Partial<OAuthDeviceCode>, "userCode">

the device code but its user code

Returns

Promise<string>

the user code

decideDevice()

protected decideDevice(pending, update): Promise<boolean>

Defined in: packages/oauth/src/oauthserver.service.ts:1068

Parameters

pending

PendingRequest

pending device request

update

Partial<OAuthDeviceCode>

decision

Returns

Promise<boolean>

false when the device code is gone, expired, of another client or no longer pending

delegableOperations()

protected delegableOperations(): string[]

Defined in: packages/oauth/src/oauthserver.service.ts:572

Returns

string[]

the operations a delegated token may be granted: all but the OAuth operations, which manage consent and only serve browser sessions

denyDevice()

protected denyDevice(pending): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1059

Deny a pending device authorization; a device code gone, expired or already decided is left as it is

Parameters

pending

PendingRequest

pending request

Returns

Promise<void>

deviceAuthorization()

deviceAuthorization(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1660

Device authorization endpoint (RFC 8628 §3.1, §3.2): client_id, scope?, hostname?. Every response, errors included, is JSON and never cached.

Rate limited: 20 requests per client IP in 10 minutes, then 429 with {"error": "slow_down"}

Parameters

ctx

WebContext

web context

Returns

Promise<void>

deviceClient()

protected deviceClient(clientId): Promise<OAuthClient | undefined>

Defined in: packages/oauth/src/oauthserver.service.ts:1416

Parameters

clientId

string | undefined

client_id

Returns

Promise<OAuthClient | undefined>

the client when it is a configured client allowed to use the device flow. Never fetches a metadata document: such clients never get the device flow

deviceLookup()

deviceLookup(userCode): Promise<{ redirect: string; }>

Defined in: packages/oauth/src/oauthserver.service.ts:1740

Bind a device code typed by the user to the browser: the pending request then goes through the consent page, which is never skipped for the device flow.

Rate limited on failures: 5 per browser session and 20 per client IP in 10 minutes. Every failure (malformed, unknown, expired or already decided code) is the same 404

Parameters

userCode

string

code displayed by the device, case, spaces and dashes ignored

Returns

Promise<{ redirect: string; }>

the consent page

devicePage()

devicePage(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1878

Built-in device code entry page: sends OAuth.Device.Lookup, which needs a signed-in browser. A signed-out browser goes to the configured login page first, which brings it back here with the code

Parameters

ctx

WebContext

web context

Returns

Promise<void>

once the response is written

emit()

emit<Key>(event, data): Promise<void>

Defined in: packages/core/lib/services/service.d.ts:204

Emit the event with data and wait for Promise to finish if listener returned a Promise

Type Parameters

Key

Key extends never

Parameters

event

Key

the event name

data

object[Key]

the data to process

Returns

Promise<void>

Inherited from

Service.emit

errorPage()

protected errorPage(ctx, status, message): void

Defined in: packages/oauth/src/oauthserver.service.ts:1111

Render an error to the browser, without redirecting

Parameters

ctx

WebContext

web context

status

number

HTTP status

message

string

message, never derived from the request

Returns

void

exchangeCode()

protected exchangeCode(body): Promise<TokenResponse>

Defined in: packages/oauth/src/oauthserver.service.ts:1261

Exchange an authorization code (RFC 6749 §4.1.3, PKCE RFC 7636 §4.6).

The code is consumed by a compare-and-set on usedAt before anything else is checked, so it is exchanged at most once whatever the outcome. A code presented again revokes the family issued from it

Parameters

body

Record<string, string>

token request

Returns

Promise<TokenResponse>

the tokens

exchangeDevice()

protected exchangeDevice(body): Promise<TokenResponse>

Defined in: packages/oauth/src/oauthserver.service.ts:1363

Device code grant (RFC 8628 §3.4, §3.5). The approved code is consumed by a compare-and-set of its status, so it yields tokens once

Parameters

body

Record<string, string>

token request

Returns

Promise<TokenResponse>

the tokens

exchangeRefresh()

protected exchangeRefresh(body): Promise<TokenResponse>

Defined in: packages/oauth/src/oauthserver.service.ts:1338

Refresh token grant (RFC 6749 §6): rotation, reuse detection, client binding and narrowing are done by TokenService

Parameters

body

Record<string, string>

token request

Returns

Promise<TokenResponse>

the tokens, with the rotated refresh token while offline_access is kept

familyName()

protected familyName(pending): Promise<string>

Defined in: packages/oauth/src/oauthserver.service.ts:1032

Parameters

pending

PendingRequest

approved request

Returns

Promise<string>

display name of the refresh family, e.g. "Webda CLI on remi-mbp"

findOperationsTransport()

protected findOperationsTransport(): OperationIdTransport<OperationIdTransportParameters> | undefined

Defined in: packages/oauth/src/oauthserver.service.ts:442

Returns

OperationIdTransport<OperationIdTransportParameters> | undefined

the operation-id transport, if one is configured

forget()

forget(clientId): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1638

Forget the remembered consent of the user for a client: the issued tokens stay valid

Parameters

clientId

string

client

Returns

Promise<void>

forgetGrant()

protected forgetGrant(userId, clientId): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1648

Parameters

userId

string

user

clientId

string

client

Returns

Promise<void>

getCapabilities()

getCapabilities(): Record<string, any>

Defined in: packages/core/lib/services/iservice.d.ts:60

Return the capabilities of this service.

By default returns capabilities detected at compile-time from

Returns

Record<string, any>

the result

Webda Capability-tagged

interfaces in webda.module.json.

Override to disable capabilities based on configuration:

getCapabilities() {
  const caps = super.getCapabilities();
  if (!this.parameters.enabled) delete caps["request-filter"];
  return caps;
}

Inherited from

Service.getCapabilities

getClientEvents()

getClientEvents(): string[]

Defined in: packages/core/lib/services/service.d.ts:144

Return the events that an external system can subscribe to

Returns

string[]

the list of results

Inherited from

Service.getClientEvents

getMaxListeners()

getMaxListeners(): number

Defined in: packages/core/lib/events/asynceventemitter.d.ts:84

Returns

number

Inherited from

Service.getMaxListeners

getMetric()

getMetric<T>(type, configuration): T

Defined in: packages/core/lib/services/service.d.ts:138

Add service name label

Type Parameters

T

T = Gauge<string> | Counter<string> | Histogram<string>

Parameters

type

CustomConstructor<T, [MetricConfiguration<T>]>

the type to look up

configuration

MetricConfiguration<T>

the configuration

Returns

T

the result

Inherited from

Service.getMetric

getName()

getName(): string

Defined in: packages/core/lib/services/service.d.ts:209

Get service name

Returns

string

the result string

Inherited from

Service.getName

getOpenApiReplacements()

getOpenApiReplacements(): any

Defined in: packages/core/lib/services/service.d.ts:182

Return variables for replacement in openapi

Returns

any

the result

Inherited from

Service.getOpenApiReplacements

getOperationId()

getOperationId(id): string | undefined

Defined in: packages/core/lib/services/service.d.ts:167

If undefined is returned it cancel the operation registration

Parameters

id

string

the identifier

Returns

string | undefined

the result

Inherited from

Service.getOperationId

getParameters()

getParameters(): T

Defined in: packages/core/lib/services/service.d.ts:82

Get the service parameters

Returns

T

the result

Inherited from

Service.getParameters

getService()

getService<T>(name): ServicesMap[T]

Defined in: packages/core/lib/services/service.d.ts:131

Get a service by name

Type Parameters

T

T extends keyof ServicesMap

Parameters

name

T

the name to use

Returns

ServicesMap[T]

the result map

Deprecated

Use useService, might reconsider

Inherited from

Service.getService

getState()

getState(): ServiceStates

Defined in: packages/core/lib/services/service.d.ts:55

Get the current state

Returns

ServiceStates

the result

Inherited from

Service.getState

getUrl()

getUrl(url, _methods): string

Defined in: packages/core/lib/services/service.d.ts:161

Return the full path url based on parameters

Parameters

url

string

relative url to service

_methods

HttpMethodType[]

in case we need filtering (like Store)

Returns

string

absolute url or undefined if need to skip the Route

Inherited from

Service.getUrl

grants()

grants(): Promise<RememberedGrant[]>

Defined in: packages/oauth/src/oauthserver.service.ts:1588

Remembered consents of the user

Returns

Promise<RememberedGrant[]>

the unexpired grants

init()

init(): Promise<OAuthServer<T>>

Defined in: packages/oauth/src/oauthserver.service.ts:279

Returns

Promise<OAuthServer<T>>

Overrides

Service.init

initMetrics()

initMetrics(): void

Defined in: packages/core/lib/services/service.d.ts:124

Init the metrics

Returns

void

Inherited from

Service.initMetrics

initOperations()

initOperations(): void

Defined in: packages/core/lib/services/service.d.ts:186

Init the operations from

Returns

void

Operation

decorators on this service

Inherited from

Service.initOperations

isConditionFailure()

protected isConditionFailure(err): boolean

Defined in: packages/oauth/src/oauthserver.service.ts:1328

Parameters

err

any

error thrown by a conditional write

Returns

boolean

true if the error is a failed write condition

issueCode()

protected issueCode(pending, identity, scope): Promise<string>

Defined in: packages/oauth/src/oauthserver.service.ts:1012

Create an authorization code, stored hashed

Parameters

pending

PendingRequest

pending request

identity

GrantIdentity

identity of the user

scope

Scope

granted scope

Returns

Promise<string>

the code

issuer()

issuer(ctx): string

Defined in: packages/oauth/src/oauthserver.service.ts:412

The configured issuer, or the origin of the request as computed by the HTTP layer (which only honors the forwarded headers of trusted proxies)

Parameters

ctx

WebContext

web context

Returns

string

issuer URL, without trailing slash

issueTokens()

protected issueTokens(identity, clientId, scope, name?, resource?): Promise<{ family: string; response: TokenResponse; }>

Defined in: packages/oauth/src/oauthserver.service.ts:1433

Issue the tokens of a new family for a consented identity

Parameters

identity

GrantIdentity

identity captured at consent

clientId

string

client

scope

Scope

granted scope

name?

string

display name of the family

resource?

string

resource the tokens are bound to (RFC 8707), none by default

Returns

Promise<{ family: string; response: TokenResponse; }>

the family and the response

listeners()

listeners(eventName): Function[]

Defined in: packages/core/lib/events/asynceventemitter.d.ts:139

Get all listeners for an event

Parameters

eventName

never

the event name

Returns

Function[]

the list of results

Inherited from

Service.listeners

loadCapabilities()

protected loadCapabilities(): void

Defined in: packages/core/lib/services/service.d.ts:120

Load capabilities from webda.module.json metadata into _compiledCapabilities.

Called during resolve after dependency injection. Reads the service's type name from parameters, looks it up in the application's module metadata (moddas or beans section), and populates _compiledCapabilities with an empty object for each declared capability name.

Fails silently if the application is not available (e.g., in unit tests where services are instantiated without a full application context).

Returns

void

Example

// If webda.module.json contains:
// { "moddas": { "MyApp/HawkService": { "capabilities": ["request-filter", "cors-filter"] } } }
// Then after resolve(), this.getCapabilities() returns:
// { "request-filter": {}, "cors-filter": {} }

See

getCapabilities

Inherited from

Service.loadCapabilities

log()

log(level, ...args): void

Defined in: packages/core/lib/services/service.d.ts:226

Parameters

level

WorkerLogLevel

to log

args

...any[]

additional arguments

Returns

void

Inherited from

Service.log

metadata()

metadata(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:452

Authorization server metadata (RFC 8414)

Parameters

ctx

WebContext

web context

Returns

Promise<void>

metadataHost()

protected metadataHost(client): string | undefined

Defined in: packages/oauth/src/oauthserver.service.ts:824

Parameters

client

OAuthClient

requesting client

Returns

string | undefined

the host publishing a metadata document client, undefined for the others

newUserCode()

protected newUserCode(): string

Defined in: packages/oauth/src/oauthserver.service.ts:1708

Returns

string

a random user code

off()

off<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:116

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.off

Inherited from

Service.off

on()

on<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:102

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.once

Inherited from

Service.on

once()

once<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:95

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.once

Inherited from

Service.once

pageUrl()

pageUrl(ctx, kind): string

Defined in: packages/oauth/src/oauthserver.service.ts:421

Parameters

ctx

WebContext

web context

kind

"device" | "consent" | "result"

page

Returns

string

absolute URL of the page: the configured one, or the built-in page

pendingPath()

protected pendingPath(ctx): string

Defined in: packages/oauth/src/oauthserver.service.ts:435

Parameters

ctx

WebContext

web context

Returns

string

path of the pending request cookie: the server url, below the deployment prefix

pruneLookupFailures()

protected pruneLookupFailures(now): void

Defined in: packages/oauth/src/oauthserver.service.ts:1854

Forget the failed lookups out of the window

Parameters

now

number

current time

Returns

void

queryParameter()

protected queryParameter(ctx, name): string | undefined

Defined in: packages/oauth/src/oauthserver.service.ts:1142

Parameters

ctx

WebContext

web context

name

string

query parameter

Returns

string | undefined

its value, capped, undefined when absent or not a string

recordAttempt()

protected recordAttempt(attempts, keys, now): void

Defined in: packages/oauth/src/oauthserver.service.ts:1825

Parameters

attempts

Map<string, number[]>

rate limit state

keys

string[]

rate limit keys

now

number

time of the attempt

Returns

void

recordLookupFailure()

protected recordLookupFailure(keys, now): void

Defined in: packages/oauth/src/oauthserver.service.ts:1816

Parameters

keys

string[]

rate limit keys

now

number

time of the failure

Returns

void

redirect()

protected redirect(ctx, url): void

Defined in: packages/oauth/src/oauthserver.service.ts:1087

Redirect without caching

Parameters

ctx

WebContext

web context

url

string

target

Returns

void

redirectHost()

protected redirectHost(redirectUri): string | undefined

Defined in: packages/oauth/src/oauthserver.service.ts:833

Parameters

redirectUri

string | undefined

redirect URI of the pending request

Returns

string | undefined

where an unverified client redirects: its host, or "local application" for loopback and private-use scheme redirects

redirectWith()

protected redirectWith(ctx, uri, params): void

Defined in: packages/oauth/src/oauthserver.service.ts:1098

Redirect to a validated URI with extra query parameters, keeping its own

Parameters

ctx

WebContext

web context

uri

string

validated redirect URI

params

Record<string, string | undefined>

parameters, undefined values are skipped

Returns

void

refreshFamily()

protected refreshFamily(token, clientId): Promise<string | undefined>

Defined in: packages/oauth/src/oauthserver.service.ts:1523

Parameters

token

string

presented token

clientId

string

authenticated client

Returns

Promise<string | undefined>

the family of the refresh token, when it is one issued to the client

register()

register(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:506

Dynamic client registration endpoint (RFC 7591): public clients only, rate limited per client IPv4 address or IPv6 /64 prefix. 404 when registration is off

Parameters

ctx

WebContext

web context

Returns

Promise<void>

registrationOpen()

protected registrationOpen(): boolean

Defined in: packages/oauth/src/oauthserver.service.ts:481

Returns

boolean

true when dynamic client registration is open: configured, or a protected resource is registered

remember()

protected remember(userId, clientId, scope): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:966

Remember the consent of a user for a client, adding to the previous one when still valid

Parameters

userId

string

user

clientId

string

client

scope

Scope

granted scope

Returns

Promise<void>

rememberedCovers()

protected rememberedCovers(ctx, remembered, requested): Promise<boolean>

Defined in: packages/oauth/src/oauthserver.service.ts:738

Whether a remembered consent answers a request: it covers every operation the request matches that the user can call now (an operation added or made callable since is asked again), grants at least one of them, and offline_access when requested. Checked on operations, not globs: a * request remembered as group globs is answered

Parameters

ctx

WebContext

web context of the user

remembered

Scope

remembered scope

requested

Scope

requested scope

Returns

Promise<boolean>

true when the consent page can be skipped

rememberedScope()

protected rememberedScope(userId, clientId): Promise<Scope | undefined>

Defined in: packages/oauth/src/oauthserver.service.ts:719

Remembered consent of a user for a client

Parameters

userId

string

user

clientId

string

client

Returns

Promise<Scope | undefined>

the remembered scope, undefined when none, expired or when remembering consent is disabled

removeAllListeners()

removeAllListeners<Key>(eventName?): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:122

Type Parameters

Key

Key extends never

Parameters

eventName?

Key

the event name

Returns

this

this for chaining

See

EventEmitter.removeAllListeners

Inherited from

Service.removeAllListeners

removeListener()

removeListener<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:109

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.removeListener

Inherited from

Service.removeListener

requestedScope()

protected requestedScope(client, raw): Scope

Defined in: packages/oauth/src/oauthserver.service.ts:680

Scope of an authorization request

Parameters

client

OAuthClient

requesting client

raw

string | undefined

scope parameter, the client default scope when absent

Returns

Scope

the parsed scope

Throws

InvalidScope when too long, malformed, beyond the client allowed scope or without any operation

requirePending()

protected requirePending(ctx): Promise<PendingRequest>

Defined in: packages/oauth/src/oauthserver.service.ts:922

The pending request of a browser session, bound to its user

Parameters

ctx

WebContext

web context

Returns

Promise<PendingRequest>

the pending request

Throws

Unauthorized without a browser (cookie) session logged in

Throws

BadRequest without a pending request

Throws

Forbidden when the request belongs to another user

resolve()

resolve(): this

Defined in: packages/oauth/src/oauthserver.service.ts:251

Returns

this

Overrides

Service.resolve

resolveResource()

protected resolveResource(ctx, client, requested?): string | undefined

Defined in: packages/oauth/src/oauthserver.service.ts:701

Resource the tokens of an authorization request are bound to (RFC 8707): only a registered protected resource. Without resource, the client default resource; else, for registered and metadata document clients, the only registered resource; static clients without a default resource get tokens bound to no resource

Parameters

ctx

WebContext

web context

client

OAuthClient

requesting client

requested?

string

resource parameter

Returns

string | undefined

the absolute URI of the resource, undefined for tokens bound to no resource

Throws

OAuthError invalid_target when the resource is not registered or cannot be chosen

resultPage()

resultPage(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1895

Built-in result page

Parameters

ctx

WebContext

web context

Returns

Promise<void>

revoke()

revoke(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1498

Revocation endpoint (RFC 7009): a refresh or access token issued to the client revokes its whole family. Any other token, unknown, invalid or issued to another client, is ignored with the same 200 response

Parameters

ctx

WebContext

web context

Returns

Promise<void>

revokeRegisteredClient()

protected revokeRegisteredClient(clientId): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:363

Revoke every refresh family issued to a client and forget the consents given to it

Parameters

clientId

string

client

Returns

Promise<void>

revokeSession()

revokeSession(family?, clientId?): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1607

Revoke a refresh family of the user, or every family of the user for a client and its remembered consent. A family of another user is ignored

Parameters

family?

string

family to revoke

clientId?

string

client whose families are revoked

Returns

Promise<void>

scopesSupported()

protected scopesSupported(): string[]

Defined in: packages/oauth/src/oauthserver.service.ts:579

Returns

string[]

advertised scopes: configured, or *, the top-level operation groups and offline_access

sessions()

sessions(): Promise<ConnectedSession[]>

Defined in: packages/oauth/src/oauthserver.service.ts:1560

Connected apps of the user: the live refresh families issued to OAuth clients

Returns

Promise<ConnectedSession[]>

the current token of each live family

setMaxListeners()

setMaxListeners(n): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:88

Parameters

n

number

Returns

this

Inherited from

Service.setMaxListeners

stop()

stop(): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:289

Returns

Promise<void>

Overrides

Service.stop

supportedScope()

protected supportedScope(requested): string | undefined

Defined in: packages/oauth/src/oauthserver.service.ts:489

Parameters

requested

string

scope string of a registration

Returns

string | undefined

the requested scope tokens the server advertises, undefined when none

sweep()

sweep(): Promise<number>

Defined in: packages/oauth/src/oauthserver.service.ts:301

Delete the expired OAuth records: authorization codes an access token lifetime after their expiry (a used code is kept that long to detect its reuse), device codes and remembered consents once expired. A sweep started while another runs joins it

Returns

Promise<number>

number of deleted records

sweepBatches()

protected sweepBatches<M>(query, remove): Promise<number>

Defined in: packages/oauth/src/oauthserver.service.ts:379

Delete matching records by batches: a batch is read, then deleted, so deleting never shifts the pages of a running query. Repeated until a batch is not full or deletes nothing

Type Parameters

M

M

Parameters

query

() => AsyncIterable<M>

query of the records to delete, run again for each batch

remove

(item) => Promise<boolean>

delete a record, false when it was kept

Returns

Promise<number>

number of deleted records

sweepExpired()

protected sweepExpired(): Promise<number>

Defined in: packages/oauth/src/oauthserver.service.ts:311

Returns

Promise<number>

number of deleted records

toJSON()

toJSON(): string

Defined in: packages/core/lib/services/service.d.ts:191

Prevent service to be serialized

Returns

string

the result

Inherited from

Service.toJSON

token()

token(ctx): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1152

Token endpoint: authorization code, refresh token and device code grants. Accepts form-encoded and JSON bodies; every response, errors included, is JSON and never cached

Parameters

ctx

WebContext

web context

Returns

Promise<void>

tokenBody()

protected tokenBody(ctx): Promise<Record<string, string>>

Defined in: packages/oauth/src/oauthserver.service.ts:1203

Parameters

ctx

WebContext

web context

Returns

Promise<Record<string, string>>

the string parameters of a form-encoded or JSON body

Throws

OAuthError invalid_request on an unreadable body, another content type or a repeated parameter

tokenResponse()

protected tokenResponse(tokens, scope): Promise<TokenResponse>

Defined in: packages/oauth/src/oauthserver.service.ts:1478

Parameters

tokens

IssuedTokens

issued tokens

scope

Scope

granted scope

Returns

Promise<TokenResponse>

the response; without offline_access the refresh token is withheld and made unusable

tokenService()

protected tokenService(): TokenService

Defined in: packages/oauth/src/oauthserver.service.ts:1249

Returns

TokenService

the token service

toOAuthError()

protected toOAuthError(err): OAuthError

Defined in: packages/oauth/src/oauthserver.service.ts:1185

Parameters

err

unknown

error raised while serving a token request

Returns

OAuthError

the RFC 6749 error to send: never an internal message

toString()

toString(): string

Defined in: packages/core/lib/services/service.d.ts:91

Return service representation

Returns

string

the result

Inherited from

Service.toString

touchGrant()

protected touchGrant(userId, clientId): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:749

Record the use of a remembered consent

Parameters

userId

string

user

clientId

string

client

Returns

Promise<void>

touchRegisteredClient()

protected touchRegisteredClient(clientId): Promise<void>

Defined in: packages/oauth/src/oauthserver.service.ts:1462

A registered client was used: extend its lifetime to the idle TTL

Parameters

clientId

string

dcr_ client_id

Returns

Promise<void>

withdrawLookupFailure()

protected withdrawLookupFailure(keys, time): void

Defined in: packages/oauth/src/oauthserver.service.ts:1842

Parameters

keys

string[]

rate limit keys

time

number

time of the failure recorded for the attempt

Returns

void

writePage()

protected writePage(ctx, status, render): void

Defined in: packages/oauth/src/oauthserver.service.ts:1121

Write a built-in page: not cached, not framed, only its nonce-bound script runs

Parameters

ctx

WebContext

web context

status

number

HTTP status

render

(nonce) => string

render the page with the nonce of its script

Returns

void

Class: OAuthServer<T>

Webda Modda​

Extends​

Type Parameters​

T​

Constructors​

Constructor​

Parameters​

name​

params​

Returns​

Inherited from​

Properties​

_compiledCapabilities​

See​

Inherited from​

[WEBDA_EVENTS]​

Inherited from​

clients​

deviceRequests​

logger​

Inherited from​

lookupFailures​

metrics?​

Inherited from​

name​

Inherited from​

parameters​

Inherited from​

registrationRequests​

sweeping?​

sweepTimer?​

createConfiguration?​

Parameters​

params​

Returns​

Inherited from​

filterConfiguration?​

Parameters​

params​

Returns​

Inherited from​

Parameters​

Inherited from​

Methods​

__clean()​

Returns​

Inherited from​

accessFamily()​

Parameters​

token​

clientId​

issuer​

Returns​

accessTtl()​

Returns​

addListener()​

Type Parameters​

Key​

Parameters​

eventName​

listener​

Returns​

See​

Inherited from​

addRoute()​

Parameters​

url​

methods​

executer​

openapi?​

override?​

Returns​

Inherited from​

approveCode()​

Parameters​

ctx​

pending​

scope​

Returns​

Webda Modda

Extends

Type Parameters

T

Constructors

Constructor

Parameters

name

params

Returns

Inherited from

Properties

_compiledCapabilities

See

Inherited from

[WEBDA_EVENTS]

Inherited from

clients

deviceRequests

logger

Inherited from

lookupFailures

metrics?

Inherited from

name

Inherited from

parameters

Inherited from

registrationRequests

sweeping?

sweepTimer?

createConfiguration?

Parameters

params

Returns

Inherited from

filterConfiguration?

Parameters

params

Returns

Inherited from

Parameters

Inherited from

Methods

__clean()

Returns

Inherited from

accessFamily()

Parameters

token

clientId

issuer

Returns

accessTtl()

Returns

addListener()

Type Parameters

Key

Parameters

eventName

listener

Returns

See

Inherited from

addRoute()

Parameters

url

methods

executer

openapi?

override?

Returns

Inherited from

approveCode()

Parameters

ctx

pending

scope

Returns

approveDevice()