ts-oauth2-server

For simpler deployments, you can store scopes as arrays (e.g., TEXT[]) directly on the oauth_clients, oauth_auth_codes, and oauth_tokens tables instead of using pivot tables.

Warning: This approach sacrifices referential integrity. There is no foreign key validation for scope names, it is harder to query 'which clients have this scope', and deleting a scope from the oauth_scopes table will not automatically remove it from the arrays in other tables.

CREATE TABLE oauth_clients (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    secret VARCHAR(255),
    redirect_uris TEXT[] NOT NULL DEFAULT '{}',
    allowed_grants VARCHAR(50)[] NOT NULL DEFAULT '{}',
    scopes TEXT[] NOT NULL DEFAULT '{}', -- Array instead of pivot table
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ
);

-- Example query for array-based scopes:
-- SELECT * FROM oauth_clients WHERE 'admin' = ANY(scopes);

The library manages three primary types of tokens, each with distinct purposes and audiences:

• Access Token: A JWT used as a bearer token to access protected resources. If an audience parameter is supplied in the request, it becomes the aud claim (the resource audience). If no audience is requested, the token has no aud claim.
• ID Token: A JWT returned only when the openid scope is granted. It asserts that an end-user authenticated. Its aud claim is the Client, which is intentionally different from an Access Token's audience.
• Refresh Token: A token used to obtain new Access Tokens. Note that in v1, the refresh flow is OIDC-unaware and does not return an ID Token.

Opaque Tokens: You can configure the server to return random strings instead of signed JWTs using useOpaqueAuthorizationCodes and useOpaqueRefreshTokens. When using opaque tokens, the persisted database row is the sole source of truth, as the token itself carries no claims.

Request

The server extracts the Access Token from the following locations (in order):

1. The Authorization: Bearer <token> header.
2. The access_token parameter in the form body.

Note: The server does not accept the token via query parameters for security reasons.

Response

A successful response returns 200 OK with Content-Type: application/json and Cache-Control: no-store.

The body contains the sub claim and any other claims permitted by the granted scopes. The library uses your getUserClaims(subject) callback to fetch attributes and then filters them based on the authorized scopes.

Important: The sub claim is controlled by the server and is derived from the canonical subject of the Access Token. It is identical to the sub in the ID Token and cannot be modified by your getUserClaims callback.

GET /userinfo HTTP/1.1
Host: auth.example.com
Authorization: Bearer <access_token>

The OIDC layer provides two distinct callbacks for supplying user information. Choosing the correct one depends on whether the data should be retrieved via a separate UserInfo request or embedded directly in the ID Token.

Comparison Table

Decision Rule: If a claim describes the user profile and the client can fetch it via a second request, use getUserClaims. If the claim must be available to the client immediately without a second request, use getIdTokenClaims.

The server uses a 'verified, persisted state' trust model for introspection and revocation. This means a token's claims are only trusted after the configured JwtInterface.verify succeeds.

Key behaviors:

• Verification: Tokens are verified using the configured algorithm. Expiry (exp) and Not-Before (nbf) are ignored during the initial parse to ensure expired tokens can still be revoked, but the active status in the introspection response is determined by the stored state (checking if the record exists, is not expired, and has not been revoked).
• Token Identification: The token type is identified by the verified payload shape rather than the token_type_hint. A payload with jti is treated as an access token, while a payload with refresh_token_id is treated as a refresh token.
• Response Priority: In introspection responses, the verified payload is processed first, but persisted database fields (active, scope, client_id, token_type) always take precedence to prevent response spoofing.
• Error Handling: If a token is unknown or cannot be found in the repository, the introspection response returns active: false instead of a 500 error, adhering to RFC 7662 §2.2.
• Opaque Tokens: When useOpaqueRefreshTokens is enabled, non-JWT strings are resolved via the grant's RefreshTokenEncoder.