matrix-nodejs-homeserver 0.3.4 → 0.3.6

package/dist/core/auth.d.ts

@@ -13,6 +13,11 @@ export interface Session {
   suspended?: boolean;
   /** Set when the request was made with an application service token. */
   appservice?: AppServiceRegistration;
+  /**
+   * The token comes from the OAuth 2.0 API (this server's or a delegated one), so endpoints that
+   * need User-Interactive Authentication send the user to account management instead.
+   */
+  oauth?: boolean;
 }
 export interface CreatedSession {
   user_id: string;
@@ -20,6 +25,8 @@ export interface CreatedSession {
   access_token: string;
   refresh_token?: string;
   expires_in_ms?: number;
+  /** OAuth 2.0 API: the scope the tokens were issued for. */
+  scope?: string;
 }
 export declare class AuthService {
   private hs;
@@ -31,9 +38,33 @@ export declare class AuthService {
     deviceId?: string;
     displayName?: string;
     refreshToken?: boolean;
+    /** OAuth 2.0 API: the client the tokens are issued to. */
+    clientId?: string;
+    /** Access token lifetime; default `accessTokenLifetimeMs` (for tokens with a refresh token). */
+    lifetimeMs?: number;
+    /** OAuth 2.0 API: the scope granted. */
+    scope?: string;
+  }): Promise<CreatedSession>;
+  issueToken(userId: string, deviceId: string, withRefresh: boolean, opts?: {
+    clientId?: string | null;
+    lifetimeMs?: number;
+    parent?: string;
+    scope?: string | null;
+  }): Promise<CreatedSession>;
+  /**
+   * Exchange a refresh token for new tokens.
+   *
+   * https://github.com/k18k/matrix-nodejs-homeserver/issues/66: the old row used to be deleted
+   * at once, so a client whose response was lost could not retry and was logged out, and a
+   * refresh token used twice went unnoticed. As the OAuth 2.0 API asks (and the legacy API
+   * allows): the old refresh token keeps working until the new access token is first used; a
+   * retry before that replaces the unused tokens. Once the new token was used, the old refresh
+   * token is spent, and presenting it again means it leaked, so the device is logged out.
+   */
+  refresh(refreshToken: string, opts?: {
+    clientId?: string | null;
+    lifetimeMs?: number;
   }): Promise<CreatedSession>;
-  issueToken(userId: string, deviceId: string, withRefresh: boolean): Promise<CreatedSession>;
-  refresh(refreshToken: string): Promise<CreatedSession>;
   /** Drop cached sessions of a user (after admin/deactivation changes). */
   invalidateUser(userId: string): Promise<void>;
   /** Issue a short-lived single-use `m.login.token` for a user (SSO, or host-app sign-in). */

package/dist/core/auth.js

@@ -11,13 +11,13 @@ var AuthService = class {
 			if (msg?.from === hs.instanceId) return;
 			if (msg.token) this.cache.delete(msg.token);
 			if (msg.userId) {
-				for (const [t, s] of this.cache) if (s.userId === msg.userId) this.cache.delete(t);
+				for (const [t, e] of this.cache) if (e.session.userId === msg.userId) this.cache.delete(t);
 			}
 		});
 	}
 	async authenticate(token, ip) {
 		const cached = this.cache.get(token);
-		if (cached) return cached;
+		if (cached && cached.expires > Date.now()) return cached.session;
 		const row = await this.hs.db.findOne("access_tokens", [{
 			field: "token",
 			value: token
@@ -39,9 +39,24 @@ var AuthService = class {
 			isGuest: !!user.is_guest,
 			isAdmin: !!user.is_admin,
 			locked: !!user.locked,
-			suspended: !!user.suspended
+			suspended: !!user.suspended,
+			...row.client_id ? { oauth: true } : {}
 		};
-		if (row.expires_ts === null) this.cache.set(token, session);
+		if (row.refresh_parent) {
+			await this.hs.db.update("access_tokens", [{
+				field: "token",
+				value: row.refresh_parent
+			}], { refresh_used: true });
+			await this.hs.db.update("access_tokens", [{
+				field: "token",
+				value: token
+			}], { refresh_parent: null });
+		}
+		if (this.cache.size > 1e5) this.cache.clear();
+		this.cache.set(token, {
+			session,
+			expires: row.expires_ts ?? Infinity
+		});
 		await this.hs.db.update("devices", [{
 			field: "user_id",
 			value: row.user_id
@@ -91,46 +106,94 @@ var AuthService = class {
 				target: deviceId
 			});
 		}
-		return this.issueToken(userId, deviceId, !!opts.refreshToken);
+		return this.issueToken(userId, deviceId, !!opts.refreshToken, {
+			clientId: opts.clientId,
+			lifetimeMs: opts.lifetimeMs,
+			scope: opts.scope
+		});
 	}
-	async issueToken(userId, deviceId, withRefresh) {
+	async issueToken(userId, deviceId, withRefresh, opts = {}) {
 		const token = `mat_${randomToken()}`;
-		const lifetime = this.hs.config.accessTokenLifetimeMs;
+		const lifetime = opts.lifetimeMs ?? this.hs.config.accessTokenLifetimeMs;
 		const refresh = withRefresh ? `mar_${randomToken()}` : null;
 		await this.hs.db.create("access_tokens", {
 			token,
 			user_id: userId,
 			device_id: deviceId,
 			refresh_token: refresh,
-			expires_ts: refresh && lifetime ? Date.now() + lifetime : null
+			expires_ts: refresh && lifetime ? Date.now() + lifetime : null,
+			client_id: opts.clientId ?? null,
+			scope: opts.scope ?? null,
+			refresh_parent: opts.parent ?? null,
+			refresh_used: false
 		});
 		const out = {
 			user_id: userId,
 			device_id: deviceId,
 			access_token: token
 		};
+		if (opts.scope) out.scope = opts.scope;
 		if (refresh) {
 			out.refresh_token = refresh;
 			if (lifetime) out.expires_in_ms = lifetime;
 		}
 		return out;
 	}
-	async refresh(refreshToken) {
-		const row = await this.hs.db.findOne("access_tokens", [{
-			field: "refresh_token",
-			value: refreshToken
-		}]);
-		if (!row) throw errors.unknownToken("Unknown refresh token");
-		await this.hs.db.delete("access_tokens", [{
-			field: "token",
-			value: row.token
-		}]);
-		this.cache.delete(row.token);
-		return this.issueToken(row.user_id, row.device_id, true);
+	/**
+	* Exchange a refresh token for new tokens.
+	*
+	* https://github.com/k18k/matrix-nodejs-homeserver/issues/66: the old row used to be deleted
+	* at once, so a client whose response was lost could not retry and was logged out, and a
+	* refresh token used twice went unnoticed. As the OAuth 2.0 API asks (and the legacy API
+	* allows): the old refresh token keeps working until the new access token is first used; a
+	* retry before that replaces the unused tokens. Once the new token was used, the old refresh
+	* token is spent, and presenting it again means it leaked, so the device is logged out.
+	*/
+	async refresh(refreshToken, opts = {}) {
+		return this.hs.cluster.lock(`refresh:${refreshToken}`, async () => {
+			const row = await this.hs.db.findOne("access_tokens", [{
+				field: "refresh_token",
+				value: refreshToken
+			}]);
+			if (!row) throw errors.unknownToken("Unknown refresh token");
+			if (opts.clientId !== void 0 && (row.client_id ?? null) !== opts.clientId) throw errors.unknownToken("Unknown refresh token");
+			if (row.refresh_used) {
+				this.hs.logger.warn("A spent refresh token was used again; logging out", row.user_id, row.device_id);
+				await this.hs.audit.record({
+					action: "logout",
+					actor: row.user_id,
+					target: row.device_id,
+					details: { refresh_token_reuse: true }
+				});
+				await this.deleteDevice(row.user_id, row.device_id);
+				throw errors.unknownToken("Refresh token was already used");
+			}
+			for (const unused of await this.hs.db.findMany("access_tokens", { where: [{
+				field: "refresh_parent",
+				value: row.token
+			}] })) await this.revokeToken(unused.token);
+			if (row.expires_ts === null || row.expires_ts > Date.now()) {
+				await this.hs.db.update("access_tokens", [{
+					field: "token",
+					value: row.token
+				}], { expires_ts: Date.now() });
+				this.cache.delete(row.token);
+				await this.hs.cluster.publish("auth", {
+					from: this.hs.instanceId,
+					token: row.token
+				});
+			}
+			return this.issueToken(row.user_id, row.device_id, true, {
+				clientId: row.client_id,
+				lifetimeMs: opts.lifetimeMs,
+				parent: row.token,
+				scope: row.scope
+			});
+		});
 	}
 	/** Drop cached sessions of a user (after admin/deactivation changes). */
 	async invalidateUser(userId) {
-		for (const [token, s] of this.cache) if (s.userId === userId) this.cache.delete(token);
+		for (const [token, e] of this.cache) if (e.session.userId === userId) this.cache.delete(token);
 		await this.hs.cluster.publish("auth", {
 			from: this.hs.instanceId,
 			userId

package/dist/core/oauth.js

@@ -89,7 +89,8 @@ var OAuthDelegation = class {
 			deviceId,
 			accessToken: token,
 			isGuest: false,
-			isAdmin: !!user.is_admin || scopes.includes(this.options.adminScope ?? "urn:synapse:admin:*")
+			isAdmin: !!user.is_admin || scopes.includes(this.options.adminScope ?? "urn:synapse:admin:*"),
+			oauth: true
 		};
 		const ttl = this.options.cacheTtlMs ?? 6e4;
 		const exp = typeof claims.exp === "number" ? claims.exp * 1e3 : Infinity;

package/dist/core/oauthserver.d.ts

@@ -0,0 +1,141 @@
+import { Homeserver } from "../homeserver.js";
+//#region src/core/oauthserver.d.ts
+export interface OAuthServerOptions {
+  /**
+   * Keep the legacy login API (`/login`, `/register`) next to the OAuth 2.0 API. Its `m.login.sso`
+   * flow then goes through the same web login and is marked `oauth_aware_preferred`. Default: true.
+   */
+  legacyApi?: boolean;
+  /** Lifetime of access tokens issued through the OAuth 2.0 API, in ms. Default: 5 minutes. */
+  accessTokenLifetimeMs?: number;
+  /** Shown on the login and registration pages: the server's terms of service and privacy policy. */
+  termsUrl?: string;
+  policyUrl?: string;
+  /** How long a browser stays logged in to the web pages, in ms. Default: 7 days. */
+  webSessionLifetimeMs?: number;
+}
+/** An OAuth error response (RFC 6749 section 5.2, RFC 7591 section 3.2.2). */
+export declare class OAuthError extends Error {
+  readonly error: string;
+  readonly description: string;
+  readonly status: number;
+  constructor(error: string, description: string, status?: number);
+}
+export interface ClientMetadata {
+  client_id: string;
+  client_uri: string;
+  client_name?: string;
+  logo_uri?: string;
+  tos_uri?: string;
+  policy_uri?: string;
+  redirect_uris: string[];
+  response_types: string[];
+  grant_types: string[];
+  token_endpoint_auth_method: "none";
+  application_type: "web" | "native";
+}
+/** A validated authorization request, waiting for the user to log in and consent. */
+export interface PendingGrant {
+  clientId: string;
+  redirectUri: string;
+  responseMode: "query" | "fragment";
+  state?: string;
+  scope: string;
+  deviceId: string;
+  codeChallenge: string;
+  nonce?: string;
+  /** The client asked for the registration page (`prompt=create`). */
+  create: boolean;
+}
+export interface DeviceGrant {
+  clientId: string;
+  scope: string;
+  deviceId: string;
+  userCode: string;
+  status: "pending" | "approved" | "denied";
+  userId?: string;
+  lastPoll: number;
+  expires: number;
+}
+export interface TokenResponse {
+  access_token: string;
+  token_type: "Bearer";
+  expires_in: number;
+  refresh_token: string;
+  scope: string;
+  id_token?: string;
+}
+export declare class OAuthServer {
+  private hs;
+  readonly options: OAuthServerOptions;
+  /** The issuer identifier: the public base URL with a trailing slash. */
+  readonly issuer: string;
+  constructor(hs: Homeserver, options: OAuthServerOptions, publicBaseUrl: string);
+  get legacyApi(): boolean;
+  get accessTokenLifetimeMs(): number;
+  /** Absolute URL of a path under the OAuth prefix. */
+  url(path: string): string;
+  get accountManagementUri(): string;
+  /** Authorization server metadata (RFC 8414), served at `/_matrix/client/v1/auth_metadata`. */
+  metadata(): Record<string, unknown>;
+  /** The server's signing key as a JWK set (RFC 8037), for ID tokens. */
+  jwks(): {
+    keys: Record<string, string>[];
+  };
+  /**
+   * Register a client. Each login registers again (the spec asks clients to), so identical
+   * metadata gets the same client ID, derived from it, instead of a new row every time.
+   */
+  registerClient(raw: Record<string, unknown>): Promise<ClientMetadata>;
+  client(clientId: string | null): Promise<ClientMetadata | null>;
+  /** Delete old registrations that no token uses (the spec forbids deleting ones in use). */
+  prune(): Promise<void>;
+  /**
+   * Check an authorization request. Problems with the client or the redirect URI are thrown as
+   * `OAuthError` with `redirect: false` semantics (shown to the user: RFC 6749 section 4.1.2.1
+   * forbids redirecting to an unverified URI); the rest come back as `{ error }` to redirect.
+   */
+  checkAuthorizationRequest(params: URLSearchParams): Promise<{
+    client: ClientMetadata;
+    grant: PendingGrant;
+  } | {
+    client: ClientMetadata;
+    redirect: string;
+    error: OAuthError;
+  }>;
+  /** The client's redirect URI with the response parameters (and RFC 9207 `iss`). */
+  callbackUrl(redirectUri: string, mode: "query" | "fragment", params: Record<string, string | undefined>): string;
+  saveGrant(grant: PendingGrant): Promise<string>;
+  grant(id: string): Promise<PendingGrant | null>;
+  /** The user approved: issue a code and return where the browser goes next. */
+  approveGrant(id: string, grant: PendingGrant, userId: string, authTime: number): Promise<string>;
+  denyGrant(id: string, grant: PendingGrant): Promise<string>;
+  token(params: URLSearchParams, clientId: string | null): Promise<TokenResponse>;
+  private exchangeCode;
+  private issue;
+  private tokenResponse;
+  /** An OpenID Connect ID token (EdDSA with the server's signing key). */
+  private idToken;
+  startDeviceGrant(clientId: string | null, scope: string | null): Promise<{
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+  }>;
+  /** The device grant a user code belongs to (typed in any case, with or without the dash). */
+  deviceGrantByUserCode(raw: string): Promise<{
+    deviceCode: string;
+    grant: DeviceGrant;
+  } | null>;
+  decideDeviceGrant(deviceCode: string, grant: DeviceGrant, userId: string, approve: boolean): Promise<void>;
+  private pollDevice;
+  /**
+   * Revoke an access or refresh token (RFC 7009). The spec revokes both tokens of the pair; a
+   * logout through this endpoint ends the device's session like `/logout` does. Unknown tokens
+   * are not an error.
+   */
+  revoke(token: string | null): Promise<void>;
+}
+//#endregion