Skip to main content

OAuthServer

@webda/oauth

Class: OAuthServer<T>

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

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

Create a new Service instance

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:50

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:288

Client resolution

deviceRequests​

deviceRequests: Map<string, number[]>

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

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:294

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:27

Name

Inherited from​

Service.name

parameters​

readonly parameters: T

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

Parameters

Inherited from​

Service.parameters

registrationRequests​

registrationRequests: Map<string, number[]>

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

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

sweeping?​

protected optional sweeping?: Promise<number>

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

Sweep in progress: a new sweep joins it

sweepTimer?​

protected optional sweepTimer?: Timeout

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

Periodic sweep of the expired OAuth records

createConfiguration?​

static optional createConfiguration?: (params) => any

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

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:39

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:224

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:1734

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

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:485

Return lifetime of the issued access tokens (s)

Returns​

number

lifetime of the issued access tokens (s)

addListener()​

addListener<Key>(eventName, listener): this

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

Add listener

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:1186

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:1232

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:685

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:1321

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:1136

Return the requested operations the user can call, in registration order

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

checkRemoteResources()​

protected checkRemoteResources(): void

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

Remote resources verify the tokens from the issuer keys: they need a fixed issuer, an asymmetric signature and the published JWKS

Returns​

void

Throws​

CodeError OAUTH_REMOTE_RESOURCES when the configuration cannot serve them

cleanHostname()​

protected cleanHostname(hostname): string | undefined

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

Clean hostname

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:1126

Clear pending

Parameters​

ctx​

WebContext

web context

Returns​

Promise<void>

codeRedirect()​

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

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

Return the client redirect carrying a new authorization code

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:1507

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:1746

Return the user managing their connected apps

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:1035

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:936

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:2077

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:2006

Count attempts

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:1994

Count lookup failures

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:1920

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:1256

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

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:663

Return the operations a delegated token may be granted: all but the OAuth operations, which manage consent

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:1246

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:1859

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:1606

Return the client when it is a configured client allowed to use the device flow. Never fetches a metadata

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:1943

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:2087

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:213

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:1299

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:1453

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:1554

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:1528

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:1219

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

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:528

Find operations transport

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:1836

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:1847

Perform forget grant

Parameters​

userId​

string

user

clientId​

string

client

Returns​

Promise<void>

getCapabilities()​

getCapabilities(): Record<string, any>

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

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:91

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:218

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

grantResources()​

protected grantResources(pending): string[]

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

Grant resources

Parameters​

pending​

PendingRequest

pending request

Returns​

string[]

the resources of its grant: the bound one first, then the others

grants()​

grants(): Promise<RememberedGrant[]>

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

Remembered consents of the user

Returns​

Promise<RememberedGrant[]>

the unexpired grants

init()​

init(): Promise<OAuthServer<T>>

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

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:195

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:1518

Check whether condition failure

Parameters​

err​

any

error thrown by a conditional write

Returns​

boolean

true if the error is a failed write condition

isRemoteResource()​

protected isRemoteResource(ctx, resource): boolean

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

Check whether remote resource

Parameters​

ctx​

WebContext

web context

resource​

string | undefined

resource of a request

Returns​

boolean

true for a resource of another application (resources): its operations and their permissions are not known here

issueCode()​

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

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

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:495

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, options?): Promise<{ family: string; response: TokenResponse; }>

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

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

options?​

issue options

audience?​

string

audience of this access token when it is one of resources

name?​

string

display name of the family

resource?​

string

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

resources?​

string[]

other resources the family may mint access tokens for (RFC 8707 §2.2)

Returns​

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

the family and the response

listeners()​

listeners(eventName): Function[]

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

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:236

Log operation

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:538

Authorization server metadata (RFC 8414)

Parameters​

ctx​

WebContext

web context

Returns​

Promise<void>

metadataHost()​

protected metadataHost(client, redirectUri?): string | undefined

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

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

Parameters​

client​

OAuthClient

requesting client

redirectUri?​

string

redirect URI of the pending request

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:1911

Return a random user code

Returns​

string

a random user code

off()​

off<Key>(eventName, listener): this

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

Perform off

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:111

Perform on

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:103

Perform once

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

operationSchemaName()​

protected operationSchemaName(method, side): string

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

Schema of an operation side: <service name>.<method>.<side> when the application knows it, else the one the build writes, <class>.<method>.<side>, for the class or its nearest ancestor that has it (a service configured under another name than its class)

Parameters​

method​

string

the method name

side​

"input" | "output"

input or output

Returns​

string

the schema name

Inherited from​

Service.operationSchemaName

pageUrl()​

pageUrl(ctx, kind): string

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

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

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:520

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

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:2063

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:1331

Query parameter

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:2033

Record attempt

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:2023

Record lookup failure

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:1275

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:1012

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

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:1286

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:1719

Refresh family

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:596

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:570

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

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:1150

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:903

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:884

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

remoteEntries()​

protected remoteEntries(requested): string[]

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

Scope entries offered for a resource of another application: the requested globs as they are, the remote application enforcing its own permissions

Parameters​

requested​

Scope

requested scope

Returns​

string[]

the requested entries but offline_access

removeAllListeners()​

removeAllListeners<Key>(eventName?): this

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

Remove all listeners

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:119

Remove listener

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:774

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:1103

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:301

Returns​

this

Overrides​

Service.resolve

resolveResource()​

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

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

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. The resources of other applications are accepted when named, never chosen by default

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

resolveResources()​

protected resolveResources(ctx, client, requested): object

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

Resources of an authorization request (RFC 8707 §2.2): the one the tokens are bound to, from the first resource parameter (see resolveResource), and the others the family may mint access tokens for: the further resource parameters and the resources of the client configuration, each a registered protected resource. The consent for a resource of another application differs, so such a resource is never combined with another one

Parameters​

ctx​

WebContext

web context

client​

OAuthClient

requesting client

requested​

string[]

resource parameters, in order

Returns​

object

the bound resource and the other ones, in request order then configuration order

resource?​

optional resource?: string

resources?​

optional resources?: string[]

Throws​

OAuthError invalid_target when a resource is not registered, cannot be chosen or is combined with one of another application

resultPage()​

resultPage(ctx): Promise<void>

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

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:1693

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:445

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:1805

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:671

Return advertised scopes: configured, or @returns advertised scopes: configured, or*, the top-level operation groups and offline_access`

Returns​

string[]

sessions()​

sessions(): Promise<ConnectedSession[]>

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

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:95

Parameters​

n​

number

Returns​

this

Inherited from​

Service.setMaxListeners

stop()​

stop(): Promise<void>

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

Returns​

Promise<void>

Overrides​

Service.stop

supportedScope()​

protected supportedScope(requested): string | undefined

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

Return the requested scope tokens the server advertises, undefined when none

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:382

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:461

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:393

Sweep expired

Returns​

Promise<number>

number of deleted records

toJSON()​

toJSON(): string

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

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:1341

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:1394

Return the string parameters of a form-encoded or JSON body

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

tokenIssuer()​

protected tokenIssuer(): string | undefined

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

Return the issuer of the access tokens, undefined when the issuer is not configured

Returns​

string | undefined

the issuer of the access tokens, undefined when the issuer is not configured

tokenResponse()​

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

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

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

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:1441

Return the token service

Returns​

TokenService

the token service

toOAuthError()​

protected toOAuthError(err): OAuthError

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

Convert to o auth error

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:914

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:1656

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:2051

Perform withdraw lookup failure

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:1309

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