@telecrypt-io/storage 0.3.0 → 0.5.7

package/dist/core/oidc.d.ts

@@ -1,69 +1,63 @@
-import { type OidcClientConfig, type OidcRegistrationClientMetadata, type DeviceAuthorizationResponse, type DeviceAccessTokenResponse, type DeviceAccessTokenError, type BearerTokenResponse } from "matrix-js-sdk/lib/oidc/index.js";
+import { type DeviceAuthorizationResponse, type DeviceAccessTokenResponse, type DeviceAccessTokenError, type BearerTokenResponse as OAuthBearerTokenResponse, type ValidatedAuthMetadata } from "matrix-js-sdk/lib/oauth/index.js";
 import type { AccessTokens, TokenRefreshFunction } from "matrix-js-sdk/lib/http-api/index.js";
-import type { IdTokenClaims } from "oidc-client-ts";
-export type { OidcClientConfig, DeviceAuthorizationResponse, DeviceAccessTokenResponse, DeviceAccessTokenError, BearerTokenResponse, AccessTokens, TokenRefreshFunction, };
-/**
- * The full result of a completed OIDC login (device-code or authorization
- * code) — enough for a caller to build a ready `TeleCryptIOStorage` via
- * `TeleCryptIOStorage.createFromOidc(...)` AND to persist for reuse/refresh
- * across restarts (CLI: profile file; UI: localStorage).
- */
-export interface OidcTokenSet {
-    homeserverUrl: string;
-    issuer: string;
-    clientId: string;
-    userId: string;
-    deviceId: string;
-    accessToken: string;
-    refreshToken?: string;
-    idToken: string;
-    /** epoch ms, if the token response included an expiry. */
-    expiresAt?: number;
+/** Matrix 1.18 OAuth metadata returned by `/auth_metadata`. */
+export type OidcClientConfig = Omit<ValidatedAuthMetadata, "revocation_endpoint"> & {
+    revocation_endpoint?: string;
+};
+export type { DeviceAuthorizationResponse, DeviceAccessTokenResponse, DeviceAccessTokenError, AccessTokens, TokenRefreshFunction };
+/** The bearer response retained by the browser authorization-code API. */
+export type BearerTokenResponse = OAuthBearerTokenResponse & {
+    scope: string;
+};
+/** The camel-case registration contract used by TeleCrypt web and CLI callers. */
+export interface OidcRegistrationClientMetadata {
+    clientName?: string;
+    clientUri: string;
+    logoUri?: string;
+    applicationType?: "web" | "native";
+    redirectUris?: [string, ...string[]];
+    contacts?: string[];
+    tosUri?: string;
+    policyUri?: string;
 }
+/** The issuer-bound endpoints accepted by the token refresh adapter. */
+export type OidcTokenEndpointMetadata = Pick<OidcClientConfig, "issuer" | "token_endpoint" | "revocation_endpoint">;
 /**
  * Discovers the OIDC/MAS issuer and endpoints for a homeserver via the
- * Matrix client's authentication metadata endpoint.
- *
- * NODE CALLERS: this internally constructs oidc-client-ts state that
- * requires `window.sessionStorage`/`window.localStorage` to exist (a real
- * browser has both natively). A Node adapter may install those only around
- * this call: a permanent global `window` breaks rust-crypto WASM's own
- * environment detection. The functional-test-only adapter is kept in
- * `test/harness/oidcWindowShim.ts`, rather than in the production SDK.
+ * Matrix client's stable `/auth_metadata` endpoint. Matrix 42 performs this
+ * as a plain metadata fetch; discovery is safe for browser and Node callers.
  */
-export declare function discoverOidcIssuer(homeserverBaseUrl: string): Promise<OidcClientConfig>;
+export declare function discoverOidcIssuer(homeserverBaseUrl: string, signal?: AbortSignal): Promise<OidcClientConfig>;
 /**
  * Dynamic client registration (DCR). `clientUri`/`redirectUris` must share a
  * host unless the issuer's policy allows a mismatch (our local dev/test MAS
  * does; a production issuer may not).
  */
-export declare function registerClient(authMetadata: OidcClientConfig, metadata: OidcRegistrationClientMetadata): Promise<string>;
+export declare function registerClient(authMetadata: OidcClientConfig, metadata: OidcRegistrationClientMetadata, signal?: AbortSignal): Promise<string>;
 /**
  * Starts a device-code authorization session. `deviceId` is caller-chosen
  * (unlike the authorization-code flow, where the SDK picks a random one) so
  * it can be reused as this Matrix device's `device_id` throughout —
- * `generateScope(deviceId)` embeds it in the requested scope per MSC2967.
+ * `generateScope(deviceId)` embeds it in the requested stable Matrix OAuth
+ * scope.
  */
-export declare function startDeviceCodeLogin(authMetadata: OidcClientConfig, clientId: string, deviceId: string): Promise<DeviceAuthorizationResponse>;
+export declare function startDeviceCodeLogin(authMetadata: OidcClientConfig, clientId: string, deviceId: string, signal?: AbortSignal): Promise<DeviceAuthorizationResponse>;
 /**
  * Polls the token endpoint until the device-code session is approved (or
  * denied/expired) — see matrix-js-sdk's `waitForDeviceAuthorization` for the
  * RFC 8628 polling semantics (honours `interval`/`expires_in`,
- * `authorization_pending`/`slow_down`).
+ * `authorization_pending`/`slow_down`). Sessions returned by
+ * startDeviceCodeLogin carry their binding in memory; reconstructed sessions
+ * must provide expectedDeviceId and are rejected before polling when no
+ * binding is available.
  */
-export declare function waitForDeviceCodeLogin(authMetadata: OidcClientConfig, clientId: string, session: DeviceAuthorizationResponse): Promise<DeviceAccessTokenResponse | DeviceAccessTokenError>;
+export declare function waitForDeviceCodeLogin(authMetadata: OidcClientConfig, clientId: string, session: DeviceAuthorizationResponse, signal?: AbortSignal, expectedDeviceId?: string): Promise<DeviceAccessTokenResponse | DeviceAccessTokenError>;
 export declare function isDeviceAccessTokenError(result: DeviceAccessTokenResponse | DeviceAccessTokenError): result is DeviceAccessTokenError;
 /**
- * Builds the authorization URL to redirect the browser to. PKCE
- * verifier/state/nonce are generated and persisted to `window.sessionStorage`
- * internally by matrix-js-sdk/oidc-client-ts (`mx_oidc_`-prefixed keys) — the
- * caller does not need to manage them; `completeAuthorizationCodeFlow` reads
- * them back after the redirect.
- *
- * `deviceId` is optional: when supplied, it is embedded in the requested
- * scope (MSC2967) so MAS grants THAT device instead of minting a fresh one —
- * the web UI passes a stable per-browser device id so repeated logins reuse
- * the same Matrix device instead of accumulating one device per login.
+ * Builds the authorization URL to redirect the browser to. The Matrix 42
+ * OAuth2 helper owns PKCE challenge generation and URL construction; this
+ * SDK owns only the minimal context needed to recreate that helper after the
+ * redirect. The context is keyed by a one-time random state in sessionStorage.
  */
 export declare function beginAuthorizationCodeFlow(opts: {
     authMetadata: OidcClientConfig;
@@ -71,52 +65,36 @@ export declare function beginAuthorizationCodeFlow(opts: {
     homeserverUrl: string;
     redirectUri: string;
     deviceId?: string;
+    signal?: AbortSignal;
 }): Promise<string>;
 /** Completes the authorization-code exchange after the `?code&state` redirect. */
-export declare function completeAuthorizationCodeFlow(code: string, state: string): Promise<{
+export declare function completeAuthorizationCodeFlow(code: string, state: string, signal?: AbortSignal): Promise<{
     tokenResponse: BearerTokenResponse;
     oidcClientSettings: {
         clientId: string;
         issuer: string;
     };
     homeserverUrl: string;
-    idTokenClaims: IdTokenClaims;
 }>;
-/** The device_id granted is embedded in the token response's `scope`
- * (`urn:matrix:org.matrix.msc2967.client:device:<id>`), per MSC2967 — the
- * authorization-code flow doesn't return it any other way (the SDK
- * auto-generates it when the caller doesn't request a specific one). */
+/** The device_id granted is embedded in the token response's stable Matrix
+ * OAuth scope. */
 export declare function extractDeviceIdFromScope(scope: string): string | null;
 /** Confirms {userId, deviceId} for a freshly-obtained access token via
  * `GET /_matrix/client/v3/account/whoami` — needed because neither the
  * device-code nor authorization-code token response includes the Matrix
  * user ID. */
-export declare function whoAmI(homeserverUrl: string, accessToken: string): Promise<{
+export declare function whoAmI(homeserverUrl: string, accessToken: string, serverName: string, signal?: AbortSignal): Promise<{
     userId: string;
     deviceId: string | null;
 }>;
-/**
- * Refreshes an access token via a plain RFC 6749 `grant_type=refresh_token`
- * POST to the token endpoint — deliberately NOT matrix-js-sdk's
- * `OidcTokenRefresher`/oidc-client-ts, which unconditionally construct an
- * internal `OidcClient` requiring `window.sessionStorage`/`window.
- * localStorage` even though a plain refresh never actually reads or writes
- * them (confirmed by direct testing: `ReferenceError: window is not
- * defined` under plain Node; see test/functional/oidc.test.ts O.2). A public client (`token_endpoint_auth_method:
- * "none"`, what `registerClient` above registers) authenticates a refresh
- * with just `client_id` in the body, no secret — this is the whole request.
- * Works identically in Node and the browser (plain `fetch`), so both
- * adapters share it with zero platform-specific code.
- */
-export declare function refreshOidcToken(tokenEndpoint: string, clientId: string, refreshToken: string): Promise<AccessTokens>;
 /**
  * Builds the `tokenRefreshFunction` `TeleCryptIOStorage.createFromOidc`
- * expects: refreshes via `refreshOidcToken`, then calls `onPersist` with the
- * new tokens before returning them — so a caller's adapter-specific
+ * expects: refreshes via the internal OAuth request, then calls `onPersist`
+ * with the new tokens before returning them — so a caller's adapter-specific
  * persistence (CLI: profile file; UI: localStorage) always sees a refresh
  * that just happened, not just ones it initiated itself.
  */
-export declare function buildTokenRefreshFunction(tokenEndpoint: string, clientId: string, onPersist: (tokens: {
+export declare function buildTokenRefreshFunction(metadata: OidcTokenEndpointMetadata, clientId: string, onPersist: (tokens: {
     accessToken: string;
     refreshToken?: string;
-}) => Promise<void>): TokenRefreshFunction;
+}, signal?: AbortSignal) => Promise<void>, expectedDeviceId: string): TokenRefreshFunction & ((refreshToken: string, signal?: AbortSignal) => Promise<AccessTokens>);