@telecrypt-io/storage 0.4.0 → 0.5.8

package/dist/core/constants.d.ts

@@ -0,0 +1,16 @@
+/** Maximum plaintext media body accepted by the non-streaming SDK surface. */
+export declare const MAX_MEDIA_FILE_BYTES: number;
+/** Matrix's canonical identifier bounds used at authenticated-client boundaries. */
+export declare const MAX_MATRIX_USER_ID_BYTES = 255;
+export declare const MAX_MATRIX_DEVICE_ID_LENGTH = 128;
+export declare const MAX_MATRIX_IDENTIFIER_LENGTH = 512;
+/**
+ * Validates a new/current Matrix identity and binds its server name exactly to
+ * the caller's independently trusted Matrix topology. The Matrix server name
+ * is deliberately explicit: a deployment may expose its homeserver through a
+ * backend hostname that differs from the user-visible Matrix server name.
+ */
+export declare function validateCanonicalMatrixUserId(value: unknown, serverName: unknown): string;
+export declare function validateMatrixDeviceId(value: unknown): string;
+export declare function validateMatrixRoomId(value: unknown, name?: string): string;
+export declare function validateMatrixEventId(value: unknown, name?: string): string;

package/dist/core/constants.js

@@ -0,0 +1,54 @@
+/** Maximum plaintext media body accepted by the non-streaming SDK surface. */
+export const MAX_MEDIA_FILE_BYTES = 128 * 1024 * 1024;
+/** Matrix's canonical identifier bounds used at authenticated-client boundaries. */
+export const MAX_MATRIX_USER_ID_BYTES = 255;
+export const MAX_MATRIX_DEVICE_ID_LENGTH = 128;
+export const MAX_MATRIX_IDENTIFIER_LENGTH = 512;
+const MATRIX_SERVER_NAME_PATTERN = "(?:\\[[0-9A-Fa-f:.]+\\]|[A-Za-z0-9.-]+)(?::\\d{1,5})?";
+const MATRIX_SERVER_NAME_REGEXP = new RegExp(`^${MATRIX_SERVER_NAME_PATTERN}$`);
+const MATRIX_USER_ID_PATTERN = new RegExp(`^@([A-Za-z0-9._=+\\-/]+):(${MATRIX_SERVER_NAME_PATTERN})$`);
+const MATRIX_DEVICE_ID_PATTERN = /^[A-Za-z0-9._~-]{1,128}$/;
+const MATRIX_ROOM_ID_PATTERN = new RegExp(`^![A-Za-z0-9._~+\\/-]+:${MATRIX_SERVER_NAME_PATTERN}$`);
+const MATRIX_EVENT_ID_PATTERN = /^\$[A-Za-z0-9._~:/+\-]{1,511}$/;
+/**
+ * Validates a new/current Matrix identity and binds its server name exactly to
+ * the caller's independently trusted Matrix topology. The Matrix server name
+ * is deliberately explicit: a deployment may expose its homeserver through a
+ * backend hostname that differs from the user-visible Matrix server name.
+ */
+export function validateCanonicalMatrixUserId(value, serverName) {
+    if (typeof value !== "string" ||
+        new TextEncoder().encode(value).byteLength > MAX_MATRIX_USER_ID_BYTES) {
+        throw new Error("invalid Matrix user ID");
+    }
+    if (typeof serverName !== "string" || !MATRIX_SERVER_NAME_REGEXP.test(serverName)) {
+        throw new Error("invalid Matrix server name");
+    }
+    const match = value.match(MATRIX_USER_ID_PATTERN);
+    if (!match || match[2].toLowerCase() !== serverName.toLowerCase()) {
+        throw new Error("invalid Matrix user ID for this homeserver");
+    }
+    return value;
+}
+export function validateMatrixDeviceId(value) {
+    if (typeof value !== "string" || value.length > MAX_MATRIX_DEVICE_ID_LENGTH || !MATRIX_DEVICE_ID_PATTERN.test(value)) {
+        throw new Error("invalid Matrix device ID");
+    }
+    return value;
+}
+export function validateMatrixRoomId(value, name = "room ID") {
+    if (typeof value !== "string" ||
+        value.length > MAX_MATRIX_IDENTIFIER_LENGTH ||
+        !MATRIX_ROOM_ID_PATTERN.test(value)) {
+        throw new Error(`invalid Matrix ${name}`);
+    }
+    return value;
+}
+export function validateMatrixEventId(value, name = "event ID") {
+    if (typeof value !== "string" ||
+        value.length > MAX_MATRIX_IDENTIFIER_LENGTH ||
+        !MATRIX_EVENT_ID_PATTERN.test(value)) {
+        throw new Error(`invalid Matrix ${name}`);
+    }
+    return value;
+}

package/dist/core/errors.d.ts

@@ -5,3 +5,69 @@
 export declare class StorageError extends Error {
     constructor(message: string);
 }
+/** Setup would replace account recovery state, which this SDK never does. */
+export declare class RecoveryAlreadyConfiguredError extends StorageError {
+    readonly code: "RECOVERY_ALREADY_CONFIGURED";
+    constructor();
+}
+/** Restore failed without exposing provider or crypto-library error details. */
+export declare class RecoveryRestoreError extends StorageError {
+    readonly code: "RECOVERY_RESTORE_FAILED";
+    constructor();
+}
+/** Setup failed before the generated Recovery Key could be safely returned. */
+export declare class RecoverySetupError extends StorageError {
+    readonly code: "RECOVERY_SETUP_FAILED";
+    constructor();
+}
+/** The recovery setup transport result is ambiguous; state must be checked before retrying. */
+export declare class RecoverySetupAmbiguousError extends StorageError {
+    readonly code: "RECOVERY_SETUP_AMBIGUOUS";
+    constructor();
+}
+/** Recovery restore was cancelled after the provider may have changed state. */
+export declare class RecoveryRestoreAmbiguousError extends StorageError {
+    readonly code: "RECOVERY_RESTORE_AMBIGUOUS";
+    constructor();
+}
+/** A Matrix mutation was cancelled after its request started. */
+export declare class MutationOutcomeUnknownError extends StorageError {
+    readonly code: "MUTATION_OUTCOME_UNKNOWN";
+    readonly operation: string;
+    constructor(operation?: string);
+}
+/** A multi-room mutation committed some work before a later step failed. */
+export declare class MutationPartialError extends StorageError {
+    readonly code: "MUTATION_PARTIAL";
+    readonly operation: string;
+    readonly completedIds: readonly string[];
+    constructor(operation: string, completedIds: readonly string[], detail?: string);
+}
+/** A vault or folder still contains files or child folders. */
+export declare class NonEmptyTreeError extends StorageError {
+    readonly code: "NON_EMPTY_TREE";
+    readonly treeId: string;
+    constructor(treeId: string);
+}
+/** Room creation timed out or returned an unusable identity. */
+export declare class RoomCreationAmbiguousError extends StorageError {
+    readonly code: "ROOM_CREATION_AMBIGUOUS";
+    readonly operation: string;
+    constructor(operation?: string);
+}
+/** A newly-created room could not be fully rolled back. */
+export declare class RoomCleanupIncompleteError extends StorageError {
+    readonly code: "ROOM_CLEANUP_INCOMPLETE";
+    readonly roomId: string;
+    constructor(roomId: string);
+}
+/** The SDK's single product file-size limit was exceeded. */
+export declare class FileTooLargeError extends StorageError {
+    readonly code: "FILE_TOO_LARGE";
+    constructor();
+}
+/** The file event is present, but this device has no key to decrypt it. */
+export declare class UndecryptableFileError extends StorageError {
+    readonly code: "FILE_UNDECRYPTABLE";
+    constructor();
+}

package/dist/core/errors.js

@@ -8,3 +8,111 @@ export class StorageError extends Error {
         this.name = "StorageError";
     }
 }
+/** Setup would replace account recovery state, which this SDK never does. */
+export class RecoveryAlreadyConfiguredError extends StorageError {
+    code = "RECOVERY_ALREADY_CONFIGURED";
+    constructor() {
+        super("recovery is already configured for this account; use the existing Recovery Key or restore it on this device");
+        this.name = "RecoveryAlreadyConfiguredError";
+    }
+}
+/** Restore failed without exposing provider or crypto-library error details. */
+export class RecoveryRestoreError extends StorageError {
+    code = "RECOVERY_RESTORE_FAILED";
+    constructor() {
+        super("recovery restore failed; verify the Recovery Key and account");
+        this.name = "RecoveryRestoreError";
+    }
+}
+/** Setup failed before the generated Recovery Key could be safely returned. */
+export class RecoverySetupError extends StorageError {
+    code = "RECOVERY_SETUP_FAILED";
+    constructor() {
+        super("recovery setup did not complete; check recovery status before retrying");
+        this.name = "RecoverySetupError";
+    }
+}
+/** The recovery setup transport result is ambiguous; state must be checked before retrying. */
+export class RecoverySetupAmbiguousError extends StorageError {
+    code = "RECOVERY_SETUP_AMBIGUOUS";
+    constructor() {
+        super("recovery setup may have completed; check recovery status before retrying");
+        this.name = "RecoverySetupAmbiguousError";
+    }
+}
+/** Recovery restore was cancelled after the provider may have changed state. */
+export class RecoveryRestoreAmbiguousError extends StorageError {
+    code = "RECOVERY_RESTORE_AMBIGUOUS";
+    constructor() {
+        super("recovery restore may have completed; check recovery status before retrying");
+        this.name = "RecoveryRestoreAmbiguousError";
+    }
+}
+/** A Matrix mutation was cancelled after its request started. */
+export class MutationOutcomeUnknownError extends StorageError {
+    code = "MUTATION_OUTCOME_UNKNOWN";
+    operation;
+    constructor(operation = "operation") {
+        super(`${operation} outcome is unknown; reconcile current state before retrying`);
+        this.name = "MutationOutcomeUnknownError";
+        this.operation = operation;
+    }
+}
+/** A multi-room mutation committed some work before a later step failed. */
+export class MutationPartialError extends StorageError {
+    code = "MUTATION_PARTIAL";
+    operation;
+    completedIds;
+    constructor(operation, completedIds, detail) {
+        super(`${operation} failed after partial completion${detail ? `: ${detail}` : ""}; retry to reconcile current state`);
+        this.name = "MutationPartialError";
+        this.operation = operation;
+        this.completedIds = [...completedIds];
+    }
+}
+/** A vault or folder still contains files or child folders. */
+export class NonEmptyTreeError extends StorageError {
+    code = "NON_EMPTY_TREE";
+    treeId;
+    constructor(treeId) {
+        super("cannot delete a nonempty vault or folder; delete its files and empty child folders first");
+        this.name = "NonEmptyTreeError";
+        this.treeId = treeId;
+    }
+}
+/** Room creation timed out or returned an unusable identity. */
+export class RoomCreationAmbiguousError extends StorageError {
+    code = "ROOM_CREATION_AMBIGUOUS";
+    operation;
+    constructor(operation = "room creation") {
+        super(`${operation} outcome is unknown; reconcile newly-created rooms before retrying`);
+        this.name = "RoomCreationAmbiguousError";
+        this.operation = operation;
+    }
+}
+/** A newly-created room could not be fully rolled back. */
+export class RoomCleanupIncompleteError extends StorageError {
+    code = "ROOM_CLEANUP_INCOMPLETE";
+    roomId;
+    constructor(roomId) {
+        super("created room cleanup is incomplete; retry cleanup for the created room");
+        this.name = "RoomCleanupIncompleteError";
+        this.roomId = roomId;
+    }
+}
+/** The SDK's single product file-size limit was exceeded. */
+export class FileTooLargeError extends StorageError {
+    code = "FILE_TOO_LARGE";
+    constructor() {
+        super("file exceeds the 128 MiB limit");
+        this.name = "FileTooLargeError";
+    }
+}
+/** The file event is present, but this device has no key to decrypt it. */
+export class UndecryptableFileError extends StorageError {
+    code = "FILE_UNDECRYPTABLE";
+    constructor() {
+        super("downloadFile: could not read file info from the event — it is likely undecryptable on this device (missing megolm session; try restoring from a Recovery Key)");
+        this.name = "UndecryptableFileError";
+    }
+}

package/dist/core/http.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Read a response body without allowing an untrusted peer to control the
+ * amount of memory consumed. Callers decide whether a truncated body is an
+ * error and retain the response status when they need provider-error mapping.
+ */
+export interface BoundedResponseBody {
+    bytes: Uint8Array<ArrayBuffer>;
+    truncated: boolean;
+}
+export interface BoundedResponseOptions {
+    /** Error returned when the body signal aborts. */
+    abortError?: () => Error;
+    /** Keep a stream reader locked until its asynchronous cancellation settles. */
+    deferReaderRelease?: boolean;
+}
+/**
+ * Reject a caller-facing operation as soon as a signal aborts. The underlying
+ * operation is deliberately not awaited after that point: browser/network
+ * implementations are allowed to ignore AbortSignal, but a bounded SDK API
+ * must still settle at its deadline. Its promise remains observed so a late
+ * rejection cannot become an unhandled rejection.
+ */
+export declare function raceWithAbort<T>(operation: PromiseLike<T>, signal: AbortSignal, onAbort: () => void, error: () => Error): Promise<T>;
+export declare function readBoundedResponseBody(response: Response, maxBytes: number, signal?: AbortSignal, options?: BoundedResponseOptions): Promise<BoundedResponseBody>;

package/dist/core/http.js

@@ -0,0 +1,199 @@
+function abortError() {
+    return new DOMException("The operation was aborted", "AbortError");
+}
+/**
+ * Reject a caller-facing operation as soon as a signal aborts. The underlying
+ * operation is deliberately not awaited after that point: browser/network
+ * implementations are allowed to ignore AbortSignal, but a bounded SDK API
+ * must still settle at its deadline. Its promise remains observed so a late
+ * rejection cannot become an unhandled rejection.
+ */
+export function raceWithAbort(operation, signal, onAbort, error) {
+    if (signal.aborted) {
+        try {
+            onAbort();
+        }
+        catch {
+            // Cleanup is best effort; the caller-facing abort error remains stable.
+        }
+        // The operation may already have been started by the caller. Observe its
+        // eventual rejection even though the public operation is already aborted.
+        void Promise.resolve(operation).catch(() => undefined);
+        return Promise.reject(error());
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => signal.removeEventListener("abort", abort);
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            callback();
+        };
+        const abort = () => {
+            // A resolved fetch can still have its abort event delivered first when a
+            // caller aborts immediately after starting it. Let an already-resolved
+            // operation hand its response to the bounded body reader, which can then
+            // cancel that reader instead of losing it in the fetch race.
+            queueMicrotask(() => {
+                finish(() => {
+                    try {
+                        onAbort();
+                    }
+                    catch {
+                        // Cleanup is best effort; the caller-facing abort error remains stable.
+                    }
+                    reject(error());
+                });
+            });
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        Promise.resolve(operation).then((value) => finish(() => resolve(value)), (reason) => finish(() => reject(reason)));
+        if (signal.aborted)
+            abort();
+    });
+}
+function cancelWithoutWaiting(cancel) {
+    try {
+        return Promise.resolve(cancel()).catch(() => undefined);
+    }
+    catch {
+        // A stream may reject cancellation synchronously; the caller is already
+        // rejecting or returning a bounded result, so cleanup remains best effort.
+        return Promise.resolve();
+    }
+}
+function releaseReaderWithoutThrowing(reader) {
+    try {
+        reader.releaseLock();
+    }
+    catch {
+        // A reader with a still-pending read can reject lock release. The bounded
+        // caller must retain its abort/size result rather than waiting for or
+        // replacing it with stream cleanup failure.
+    }
+}
+export async function readBoundedResponseBody(response, maxBytes, signal, options = {}) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+        throw new Error("invalid response body limit");
+    }
+    const cancelBody = () => {
+        if (response.body)
+            cancelWithoutWaiting(() => response.body.cancel());
+    };
+    const cancelAbortedResponse = () => {
+        if (!response.body) {
+            cancelBody();
+            return;
+        }
+        let reader;
+        try {
+            reader = response.body.getReader();
+        }
+        catch {
+            cancelBody();
+            return;
+        }
+        const cancellation = cancelWithoutWaiting(() => reader.cancel());
+        if (options.deferReaderRelease)
+            void cancellation.then(() => releaseReaderWithoutThrowing(reader));
+        else
+            releaseReaderWithoutThrowing(reader);
+    };
+    if (signal?.aborted) {
+        cancelAbortedResponse();
+        throw options.abortError?.() ?? abortError();
+    }
+    const contentLength = response.headers.get("content-length");
+    if (contentLength !== null && (!/^\d+$/.test(contentLength) || Number(contentLength) > maxBytes)) {
+        cancelBody();
+        return { bytes: new Uint8Array(), truncated: true };
+    }
+    if (!response.body)
+        return { bytes: new Uint8Array(), truncated: false };
+    const reader = response.body.getReader();
+    let cancellation;
+    const cancelReader = () => {
+        cancellation ??= cancelWithoutWaiting(() => reader.cancel());
+    };
+    const releaseReader = () => {
+        if (options.deferReaderRelease && cancellation) {
+            void cancellation.then(() => releaseReaderWithoutThrowing(reader));
+        }
+        else {
+            releaseReaderWithoutThrowing(reader);
+        }
+    };
+    const chunks = [];
+    let bytesRead = 0;
+    const readChunk = () => {
+        if (!signal)
+            return reader.read();
+        if (signal.aborted) {
+            cancelReader();
+            return Promise.reject(options.abortError?.() ?? abortError());
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => signal.removeEventListener("abort", onAbort);
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cancelReader();
+                cleanup();
+                reject(options.abortError?.() ?? abortError());
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            reader.read().then((result) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve(result);
+            }, (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            });
+        });
+    };
+    try {
+        for (;;) {
+            const { done, value } = await readChunk();
+            if (done)
+                break;
+            const remaining = maxBytes - bytesRead;
+            if (value.byteLength > remaining) {
+                if (remaining > 0) {
+                    const chunk = new Uint8Array(remaining);
+                    chunk.set(value.subarray(0, remaining));
+                    chunks.push(chunk);
+                    bytesRead += remaining;
+                }
+                cancelReader();
+                return { bytes: joinBytes(chunks, bytesRead), truncated: true };
+            }
+            const chunk = new Uint8Array(value.byteLength);
+            chunk.set(value);
+            chunks.push(chunk);
+            bytesRead += value.byteLength;
+        }
+    }
+    finally {
+        releaseReader();
+    }
+    return { bytes: joinBytes(chunks, bytesRead), truncated: false };
+}
+function joinBytes(chunks, total) {
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}

package/dist/core/index.d.ts

@@ -3,3 +3,4 @@ export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";
 export * from "./oidc.js";
+export * from "./constants.js";

package/dist/core/index.js

@@ -3,3 +3,4 @@ export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";
 export * from "./oidc.js";
+export * from "./constants.js";

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>);