@lgriffin/esi.ts 9.7.0 → 10.2.0

package/dist/auth/EsiTokenManager.d.ts

@@ -0,0 +1,200 @@
+import { EsiClient, EsiClientConfig } from '../EsiClient';
+import type { FetchLike, TokenProvider } from '../core/ApiClient';
+import type { ILogger } from '../core/logger/ILogger';
+import { EveSsoClient, AuthorizationUrlOptions, ExchangeCodeOptions } from './EveSsoClient';
+import type { ITokenStorage, StoredToken } from './types';
+export interface EsiTokenManagerConfig {
+    /** The application's SSO client id. */
+    clientId: string;
+    /** The application's SSO client secret. Omit for a public (PKCE) client. */
+    clientSecret?: string;
+    /** Redirect URI registered for the application. */
+    callbackUrl?: string;
+    /** Where tokens are persisted. Defaults to {@link MemoryTokenStorage}. */
+    storage?: ITokenStorage;
+    /** Pre-built SSO client. When given, `clientId`, `clientSecret`, `callbackUrl` and `fetch` are ignored for SSO calls. */
+    ssoClient?: EveSsoClient;
+    /** Custom fetch for SSO calls. Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+    /**
+     * How long before expiry a token counts as stale, in milliseconds.
+     * Defaults to 60 000 (one minute).
+     */
+    refreshSkewMs?: number;
+    /**
+     * When true (the default), {@link EsiTokenManager.getToken} refreshes a
+     * stale token before returning it. When false it returns the stored token
+     * as-is and refresh only happens through {@link EsiTokenManager.refresh},
+     * {@link EsiTokenManager.refreshAll}, or the 401 path of a created client.
+     */
+    autoRefresh?: boolean;
+    /** Called after a token is refreshed and persisted. */
+    onRefresh?: (token: StoredToken) => void;
+    /** Called when a refresh fails for a reason other than revocation. */
+    onRefreshError?: (characterId: number, error: Error) => void;
+    /** Called when SSO reports a character's refresh token as invalid. */
+    onRevoked?: (characterId: number) => void;
+    /** Logger for refresh activity. Defaults to the library logger. */
+    logger?: ILogger;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+export interface AddCharacterOptions extends ExchangeCodeOptions {
+    /**
+     * When the character already has a stored token, revoke its refresh token
+     * at SSO before replacing it. Defaults to false.
+     */
+    revokeReplaced?: boolean;
+}
+export interface RemoveCharacterOptions {
+    /** Revoke the refresh token at SSO before deleting it. Defaults to false. */
+    revoke?: boolean;
+}
+export interface RefreshAllOptions {
+    /** Maximum simultaneous SSO requests. Defaults to 5. */
+    concurrency?: number;
+    /**
+     * Only refresh tokens that expire within this many milliseconds (after
+     * applying the refresh skew). Omit to refresh every token.
+     */
+    expiringWithinMs?: number;
+    /** Abort the run; remaining tokens are reported as skipped. */
+    signal?: AbortSignal;
+    /**
+     * Progress callback, invoked after each token settles. A callback that
+     * throws does not stop the run; the exception is discarded.
+     */
+    onProgress?: (completed: number, total: number) => void;
+}
+export type RefreshStatus = 'refreshed' | 'skipped' | 'failed' | 'revoked';
+export interface RefreshResult {
+    characterId: number;
+    status: RefreshStatus;
+    /** New expiry in epoch milliseconds, when refreshed. */
+    expiresAt?: number;
+    /** The error, when failed or revoked. */
+    error?: Error;
+    /** True when the failure was an SSO 429 or 5xx and can be retried later. */
+    retryable?: boolean;
+    /** Why the token was skipped. */
+    reason?: 'not-stale' | 'aborted';
+}
+/** Lightweight view of a stored character, without the secrets. */
+export interface CharacterSummary {
+    characterId: number;
+    characterName: string;
+    scopes: string[];
+    expiresAt: number;
+    revoked: boolean;
+}
+/** EsiClient options a manager-created client accepts; token fields are supplied by the manager. */
+export type ManagedClientConfig = Omit<EsiClientConfig, 'accessToken' | 'onTokenRefresh'>;
+/**
+ * Keeps one valid SSO token per character on top of a pluggable
+ * {@link ITokenStorage}, refreshing ahead of expiry, coalescing concurrent
+ * refreshes, persisting rotated refresh tokens, and recording revocations so
+ * SSO is not hammered with a dead refresh token.
+ */
+export declare class EsiTokenManager {
+    private readonly storage;
+    private readonly sso;
+    private readonly refreshSkewMs;
+    private readonly autoRefresh;
+    private readonly logger;
+    private readonly now;
+    private readonly hooks;
+    private readonly inFlight;
+    /**
+     * Per-character write generation. Bumped whenever a record is replaced or
+     * removed so a refresh that was already waiting on SSO can tell its result
+     * is stale and must not be persisted over the newer state.
+     */
+    private readonly generations;
+    constructor(config: EsiTokenManagerConfig);
+    /** The SSO client used for all token traffic. */
+    getSsoClient(): EveSsoClient;
+    /** The storage adapter backing this manager. */
+    getStorage(): ITokenStorage;
+    /** Build the SSO login URL. See {@link EveSsoClient.getAuthorizationUrl}. */
+    getAuthorizationUrl(options: AuthorizationUrlOptions): string;
+    /**
+     * Exchange an authorization code and store the resulting token under the
+     * character it belongs to. An existing token for that character is
+     * replaced; storage never holds two entries for one character.
+     */
+    addCharacter(code: string, options?: AddCharacterOptions): Promise<StoredToken>;
+    /**
+     * Import tokens obtained elsewhere (a previous library version, another
+     * tool, a migration). The character identity is decoded from the access
+     * token; `expiresIn` is in seconds and defaults to the JWT `exp` claim.
+     */
+    importToken(token: {
+        accessToken: string;
+        refreshToken: string;
+        expiresIn?: number;
+    }): Promise<StoredToken>;
+    /** Delete a character's token, optionally revoking it at SSO first. */
+    removeCharacter(characterId: number, options?: RemoveCharacterOptions): Promise<void>;
+    /** The stored record for a character, or null. */
+    getStoredToken(characterId: number): Promise<StoredToken | null>;
+    /** Every stored token. */
+    listTokens(): Promise<StoredToken[]>;
+    /** Every stored character without its secrets. */
+    listCharacters(): Promise<CharacterSummary[]>;
+    /** True when the stored token grants every listed scope. */
+    hasScopes(characterId: number, scopes: readonly string[]): Promise<boolean>;
+    /**
+     * A usable access token for the character. With `autoRefresh` on, a token
+     * inside the refresh skew is refreshed first.
+     *
+     * @throws CharacterNotFoundError when no token is stored
+     * @throws TokenRevokedError when the character's refresh token is revoked
+     */
+    getToken(characterId: number): Promise<string>;
+    /**
+     * Refresh a character's token through SSO regardless of expiry. Concurrent
+     * calls for the same character share one SSO request.
+     */
+    refresh(characterId: number): Promise<StoredToken>;
+    /**
+     * Refresh stored tokens with bounded concurrency. Per-character failures
+     * never reject: each character gets its own {@link RefreshResult}. The one
+     * rejection is a failing `storage.list()`, because with no records there
+     * is no character to attribute the fault to and a silent empty run would
+     * hide a broken store from a scheduler.
+     */
+    refreshAll(options?: RefreshAllOptions): Promise<RefreshResult[]>;
+    /**
+     * A {@link TokenProvider} bound to a character, for `onTokenRefresh`. Every
+     * invocation refreshes through SSO (coalesced), because the client only
+     * calls it after ESI has rejected the current token.
+     */
+    tokenProviderFor(characterId: number): TokenProvider;
+    /**
+     * An {@link EsiClient} whose access token and refresh provider are bound to
+     * the character. The token is validated (and refreshed if stale) first.
+     */
+    createClient(characterId: number, config?: ManagedClientConfig): Promise<EsiClient>;
+    private isStale;
+    private requireStored;
+    private generationOf;
+    private bumpGeneration;
+    /**
+     * After an SSO round trip, decide whether the refresh still owns the
+     * character's record. Returns null when it does. When the record was
+     * replaced meanwhile, returns the current record so the caller hands out
+     * the newer credentials; when it was removed, throws CharacterNotFoundError.
+     */
+    private supersededBy;
+    private doRefresh;
+    private refreshOne;
+    private storeResponse;
+    /**
+     * Build the record to persist. When adding a character the access token
+     * must decode, because it is the only source of the character id. On a
+     * refresh the identity is already known, so a token that does not decode
+     * (a proxy, a future SSO format) keeps the previous record's identity.
+     */
+    private buildStoredToken;
+}
+//# sourceMappingURL=EsiTokenManager.d.ts.map

package/dist/auth/EsiTokenManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EsiTokenManager.d.ts","sourceRoot":"","sources":["../../src/auth/EsiTokenManager.ts"],"names":[],"mappings":"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"}

package/dist/auth/EveSsoClient.d.mts

@@ -0,0 +1,88 @@
+import type { FetchLike } from '../core/ApiClient.mjs';
+export declare const DEFAULT_SSO_BASE_URL = "https://login.eveonline.com";
+export interface EveSsoClientConfig {
+    /** The application's client id from developers.eveonline.com. */
+    clientId: string;
+    /**
+     * The application's client secret. Omit for a public (PKCE) client; token
+     * requests then identify the application by `client_id` in the form body.
+     */
+    clientSecret?: string;
+    /** Redirect URI registered for the application. Used by {@link EveSsoClient.getAuthorizationUrl}. */
+    callbackUrl?: string;
+    /** Override the SSO host, for tests or a proxy. Defaults to https://login.eveonline.com. */
+    ssoBaseUrl?: string;
+    /** Custom fetch implementation. Defaults to `globalThis.fetch` resolved at call time. */
+    fetch?: FetchLike;
+}
+/** A successful response from the SSO token endpoint. */
+export interface SsoTokenResponse {
+    accessToken: string;
+    refreshToken: string;
+    /** Lifetime of `accessToken` in seconds, as reported by SSO. */
+    expiresIn: number;
+    tokenType: string;
+}
+export interface AuthorizationUrlOptions {
+    /** Scopes to request. */
+    scopes: readonly string[];
+    /** Opaque value echoed back on the callback; use {@link generateState}. */
+    state: string;
+    /** PKCE challenge for public clients; see {@link generatePkcePair}. */
+    codeChallenge?: string;
+    /** Overrides `callbackUrl` from the config. */
+    redirectUri?: string;
+}
+export interface ExchangeCodeOptions {
+    /** PKCE verifier that produced the challenge sent in the authorization URL. */
+    codeVerifier?: string;
+    /**
+     * The redirect URI that was sent in the authorization request. Defaults to
+     * the configured `callbackUrl`; when neither is set the field is omitted.
+     */
+    redirectUri?: string;
+}
+export interface RefreshOptions {
+    /** Request a subset of the originally granted scopes. */
+    scopes?: readonly string[];
+}
+/**
+ * Minimal client for the EVE SSO OAuth2 endpoints: building the login URL,
+ * exchanging an authorization code, refreshing, and revoking.
+ *
+ * Supports confidential clients (HTTP Basic with the client secret) and
+ * public clients (PKCE with `client_id` in the body). No JWT signature
+ * verification is performed; tokens are trusted because they arrive directly
+ * from SSO over TLS.
+ */
+export declare class EveSsoClient {
+    private readonly clientId;
+    private readonly clientSecret?;
+    private readonly callbackUrl?;
+    private readonly baseUrl;
+    private readonly fetchFn?;
+    constructor(config: EveSsoClientConfig);
+    /** True when a client secret is configured (confidential client). */
+    isConfidential(): boolean;
+    get tokenUrl(): string;
+    get authorizeUrl(): string;
+    get revokeUrl(): string;
+    /** Build the URL to send a player to for login. */
+    getAuthorizationUrl(options: AuthorizationUrlOptions): string;
+    /** Exchange the authorization code from the callback for tokens. */
+    exchangeCode(code: string, options?: ExchangeCodeOptions): Promise<SsoTokenResponse>;
+    /** Obtain a new access token (and rotated refresh token) from a refresh token. */
+    refresh(refreshToken: string, options?: RefreshOptions): Promise<SsoTokenResponse>;
+    /** Revoke a refresh token so it can no longer be used. */
+    revoke(token: string, tokenTypeHint?: 'refresh_token' | 'access_token'): Promise<void>;
+    private tokenRequest;
+    private post;
+    /**
+     * Map a non-2xx SSO response to an error. `invalid_grant` means "the
+     * refresh token is dead" only for a refresh grant; on a code exchange (or
+     * a revoke) it describes the login code or request, so it stays an
+     * `SsoError` and does not trigger the re-authentication path.
+     */
+    private errorFromResponse;
+}
+//# sourceMappingURL=EveSsoClient.d.ts.map

package/dist/auth/EveSsoClient.d.ts

@@ -0,0 +1,88 @@
+import type { FetchLike } from '../core/ApiClient';
+export declare const DEFAULT_SSO_BASE_URL = "https://login.eveonline.com";
+export interface EveSsoClientConfig {
+    /** The application's client id from developers.eveonline.com. */
+    clientId: string;
+    /**
+     * The application's client secret. Omit for a public (PKCE) client; token
+     * requests then identify the application by `client_id` in the form body.
+     */
+    clientSecret?: string;
+    /** Redirect URI registered for the application. Used by {@link EveSsoClient.getAuthorizationUrl}. */
+    callbackUrl?: string;
+    /** Override the SSO host, for tests or a proxy. Defaults to https://login.eveonline.com. */
+    ssoBaseUrl?: string;
+    /** Custom fetch implementation. Defaults to `globalThis.fetch` resolved at call time. */
+    fetch?: FetchLike;
+}
+/** A successful response from the SSO token endpoint. */
+export interface SsoTokenResponse {
+    accessToken: string;
+    refreshToken: string;
+    /** Lifetime of `accessToken` in seconds, as reported by SSO. */
+    expiresIn: number;
+    tokenType: string;
+}
+export interface AuthorizationUrlOptions {
+    /** Scopes to request. */
+    scopes: readonly string[];
+    /** Opaque value echoed back on the callback; use {@link generateState}. */
+    state: string;
+    /** PKCE challenge for public clients; see {@link generatePkcePair}. */
+    codeChallenge?: string;
+    /** Overrides `callbackUrl` from the config. */
+    redirectUri?: string;
+}
+export interface ExchangeCodeOptions {
+    /** PKCE verifier that produced the challenge sent in the authorization URL. */
+    codeVerifier?: string;
+    /**
+     * The redirect URI that was sent in the authorization request. Defaults to
+     * the configured `callbackUrl`; when neither is set the field is omitted.
+     */
+    redirectUri?: string;
+}
+export interface RefreshOptions {
+    /** Request a subset of the originally granted scopes. */
+    scopes?: readonly string[];
+}
+/**
+ * Minimal client for the EVE SSO OAuth2 endpoints: building the login URL,
+ * exchanging an authorization code, refreshing, and revoking.
+ *
+ * Supports confidential clients (HTTP Basic with the client secret) and
+ * public clients (PKCE with `client_id` in the body). No JWT signature
+ * verification is performed; tokens are trusted because they arrive directly
+ * from SSO over TLS.
+ */
+export declare class EveSsoClient {
+    private readonly clientId;
+    private readonly clientSecret?;
+    private readonly callbackUrl?;
+    private readonly baseUrl;
+    private readonly fetchFn?;
+    constructor(config: EveSsoClientConfig);
+    /** True when a client secret is configured (confidential client). */
+    isConfidential(): boolean;
+    get tokenUrl(): string;
+    get authorizeUrl(): string;
+    get revokeUrl(): string;
+    /** Build the URL to send a player to for login. */
+    getAuthorizationUrl(options: AuthorizationUrlOptions): string;
+    /** Exchange the authorization code from the callback for tokens. */
+    exchangeCode(code: string, options?: ExchangeCodeOptions): Promise<SsoTokenResponse>;
+    /** Obtain a new access token (and rotated refresh token) from a refresh token. */
+    refresh(refreshToken: string, options?: RefreshOptions): Promise<SsoTokenResponse>;
+    /** Revoke a refresh token so it can no longer be used. */
+    revoke(token: string, tokenTypeHint?: 'refresh_token' | 'access_token'): Promise<void>;
+    private tokenRequest;
+    private post;
+    /**
+     * Map a non-2xx SSO response to an error. `invalid_grant` means "the
+     * refresh token is dead" only for a refresh grant; on a code exchange (or
+     * a revoke) it describes the login code or request, so it stays an
+     * `SsoError` and does not trigger the re-authentication path.
+     */
+    private errorFromResponse;
+}
+//# sourceMappingURL=EveSsoClient.d.ts.map

package/dist/auth/EveSsoClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EveSsoClient.d.ts","sourceRoot":"","sources":["../../src/auth/EveSsoClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAInD,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAElE,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,yBAAyB;IACzB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAqBD;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAY;gBAEzB,MAAM,EAAE,kBAAkB;IActC,qEAAqE;IACrE,cAAc,IAAI,OAAO;IAIzB,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,mDAAmD;IACnD,mBAAmB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM;IAoB7D,oEAAoE;IAC9D,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,gBAAgB,CAAC;IAiB5B,kFAAkF;IAC5E,OAAO,CACX,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC;IAW5B,0DAA0D;IACpD,MAAM,CACV,KAAK,EAAE,MAAM,EACb,aAAa,GAAE,eAAe,GAAG,cAAgC,GAChE,OAAO,CAAC,IAAI,CAAC;YAWF,YAAY;YAgDZ,IAAI;IAkBlB;;;;;OAKG;YACW,iBAAiB;CA2BhC"}

package/dist/auth/errors.d.mts

@@ -0,0 +1,42 @@
+/** Base class for every error raised by the auth subsystem. */
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * EVE SSO answered a token or revoke request with a non-2xx status.
+ *
+ * `errorCode` is the OAuth2 `error` field from the response body
+ * (`invalid_client`, `invalid_request`, ...) or `unknown` when the body could
+ * not be parsed. `statusCode` is the HTTP status.
+ */
+export declare class SsoError extends AuthError {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly errorDescription?: string;
+    constructor(statusCode: number, errorCode: string, errorDescription?: string);
+    /** True for statuses where the same request can be retried later. */
+    isRetryable(): boolean;
+}
+/**
+ * The refresh token is no longer accepted by SSO (`invalid_grant`), or the
+ * manager has already recorded that outcome for the character. The character
+ * must log in again; retrying cannot help.
+ */
+export declare class TokenRevokedError extends AuthError {
+    readonly characterId?: number;
+    constructor(message: string, characterId?: number);
+}
+/** A JWT access token could not be decoded into the claims the manager needs. */
+export declare class TokenDecodeError extends AuthError {
+    constructor(message: string);
+}
+/** No token is stored for the requested character. */
+export declare class CharacterNotFoundError extends AuthError {
+    readonly characterId: number;
+    constructor(characterId: number);
+}
+export declare function isAuthError(error: unknown): error is AuthError;
+export declare function isSsoError(error: unknown): error is SsoError;
+export declare function isTokenRevoked(error: unknown): error is TokenRevokedError;
+export declare function isCharacterNotFound(error: unknown): error is CharacterNotFoundError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/auth/errors.d.ts

@@ -0,0 +1,42 @@
+/** Base class for every error raised by the auth subsystem. */
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * EVE SSO answered a token or revoke request with a non-2xx status.
+ *
+ * `errorCode` is the OAuth2 `error` field from the response body
+ * (`invalid_client`, `invalid_request`, ...) or `unknown` when the body could
+ * not be parsed. `statusCode` is the HTTP status.
+ */
+export declare class SsoError extends AuthError {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    readonly errorDescription?: string;
+    constructor(statusCode: number, errorCode: string, errorDescription?: string);
+    /** True for statuses where the same request can be retried later. */
+    isRetryable(): boolean;
+}
+/**
+ * The refresh token is no longer accepted by SSO (`invalid_grant`), or the
+ * manager has already recorded that outcome for the character. The character
+ * must log in again; retrying cannot help.
+ */
+export declare class TokenRevokedError extends AuthError {
+    readonly characterId?: number;
+    constructor(message: string, characterId?: number);
+}
+/** A JWT access token could not be decoded into the claims the manager needs. */
+export declare class TokenDecodeError extends AuthError {
+    constructor(message: string);
+}
+/** No token is stored for the requested character. */
+export declare class CharacterNotFoundError extends AuthError {
+    readonly characterId: number;
+    constructor(characterId: number);
+}
+export declare function isAuthError(error: unknown): error is AuthError;
+export declare function isSsoError(error: unknown): error is SsoError;
+export declare function isTokenRevoked(error: unknown): error is TokenRevokedError;
+export declare function isCharacterNotFound(error: unknown): error is CharacterNotFoundError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/auth/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,SAAS;IACrC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,gBAAgB,CAAC,EAAE,MAAM,CAAC;gBAGxC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,gBAAgB,CAAC,EAAE,MAAM;IAU3B,qEAAqE;IACrE,WAAW,IAAI,OAAO;CAGvB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C,SAAgB,WAAW,CAAC,EAAE,MAAM,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAKlD;AAED,iFAAiF;AACjF,qBAAa,gBAAiB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,sDAAsD;AACtD,qBAAa,sBAAuB,SAAQ,SAAS;IACnD,SAAgB,WAAW,EAAE,MAAM,CAAC;gBAExB,WAAW,EAAE,MAAM;CAKhC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAEzE;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,sBAAsB,CAEjC"}

package/dist/auth/index.d.mts

@@ -0,0 +1,14 @@
+export type { ITokenStorage, StoredToken } from './types.mjs';
+export { EveSsoClient, DEFAULT_SSO_BASE_URL } from './EveSsoClient.mjs';
+export type { EveSsoClientConfig, SsoTokenResponse, AuthorizationUrlOptions, ExchangeCodeOptions, RefreshOptions, } from './EveSsoClient.mjs';
+export { EsiTokenManager } from './EsiTokenManager.mjs';
+export type { EsiTokenManagerConfig, AddCharacterOptions, RemoveCharacterOptions, RefreshAllOptions, RefreshResult, RefreshStatus, CharacterSummary, ManagedClientConfig, } from './EsiTokenManager.mjs';
+export { MemoryTokenStorage } from './storage/MemoryTokenStorage.mjs';
+export { FileTokenStorage } from './storage/FileTokenStorage.mjs';
+export type { FileTokenStorageOptions } from './storage/FileTokenStorage.mjs';
+export { AuthError, SsoError, TokenRevokedError, TokenDecodeError, CharacterNotFoundError, isAuthError, isSsoError, isTokenRevoked, isCharacterNotFound, } from './errors.mjs';
+export { decodeAccessToken, decodeJwtPayload, parseCharacterId, parseScopes, } from './jwt.mjs';
+export type { DecodedAccessToken, EveJwtClaims } from './jwt.mjs';
+export { generatePkcePair, generateCodeVerifier, codeChallengeFromVerifier, generateState, } from './pkce.mjs';
+export type { PkcePair } from './pkce.mjs';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts

@@ -0,0 +1,14 @@
+export type { ITokenStorage, StoredToken } from './types';
+export { EveSsoClient, DEFAULT_SSO_BASE_URL } from './EveSsoClient';
+export type { EveSsoClientConfig, SsoTokenResponse, AuthorizationUrlOptions, ExchangeCodeOptions, RefreshOptions, } from './EveSsoClient';
+export { EsiTokenManager } from './EsiTokenManager';
+export type { EsiTokenManagerConfig, AddCharacterOptions, RemoveCharacterOptions, RefreshAllOptions, RefreshResult, RefreshStatus, CharacterSummary, ManagedClientConfig, } from './EsiTokenManager';
+export { MemoryTokenStorage } from './storage/MemoryTokenStorage';
+export { FileTokenStorage } from './storage/FileTokenStorage';
+export type { FileTokenStorageOptions } from './storage/FileTokenStorage';
+export { AuthError, SsoError, TokenRevokedError, TokenDecodeError, CharacterNotFoundError, isAuthError, isSsoError, isTokenRevoked, isCharacterNotFound, } from './errors';
+export { decodeAccessToken, decodeJwtPayload, parseCharacterId, parseScopes, } from './jwt';
+export type { DecodedAccessToken, EveJwtClaims } from './jwt';
+export { generatePkcePair, generateCodeVerifier, codeChallengeFromVerifier, generateState, } from './pkce';
+export type { PkcePair } from './pkce';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,YAAY,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAE1E,OAAO,EACL,SAAS,EACT,QAAQ,EACR,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,WAAW,EACX,UAAU,EACV,cAAc,EACd,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,GACZ,MAAM,OAAO,CAAC;AACf,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE9D,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,EACzB,aAAa,GACd,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC"}

package/dist/auth/jwt.d.mts

@@ -0,0 +1,43 @@
+/** Claims EVE SSO places in an access token. Only the ones the manager reads are typed. */
+export interface EveJwtClaims {
+    /** `CHARACTER:EVE:<characterId>` */
+    sub: string;
+    /** Character name. */
+    name?: string;
+    /** Granted scopes: a single string, or an array when more than one. */
+    scp?: string | string[];
+    /** Expiry as epoch seconds. */
+    exp?: number;
+    /** Issued-at as epoch seconds. */
+    iat?: number;
+    /** Owner hash; changes on character transfer. */
+    owner?: string;
+    iss?: string;
+    aud?: string | string[];
+    [claim: string]: unknown;
+}
+/** Identity and lifetime information extracted from an EVE SSO access token. */
+export interface DecodedAccessToken {
+    characterId: number;
+    characterName: string;
+    scopes: string[];
+    /** Epoch milliseconds, or undefined when the token carries no `exp`. */
+    expiresAt?: number;
+    ownerHash?: string;
+    claims: EveJwtClaims;
+}
+/**
+ * Decode the payload of a JWT without verifying its signature.
+ *
+ * Tokens reach the manager directly from SSO over TLS, so the payload is
+ * trusted for the purpose of learning which character it belongs to. Do not
+ * use this to authenticate tokens presented by third parties.
+ */
+export declare function decodeJwtPayload(token: string): EveJwtClaims;
+/** Parse the character id out of an SSO `sub` claim (`CHARACTER:EVE:123`). */
+export declare function parseCharacterId(sub: unknown): number;
+/** Normalise the `scp` claim, which SSO emits as a string for one scope and an array otherwise. */
+export declare function parseScopes(scp: unknown): string[];
+/** Decode an EVE SSO access token into the fields the token manager stores. */
+export declare function decodeAccessToken(token: string): DecodedAccessToken;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/auth/jwt.d.ts

@@ -0,0 +1,43 @@
+/** Claims EVE SSO places in an access token. Only the ones the manager reads are typed. */
+export interface EveJwtClaims {
+    /** `CHARACTER:EVE:<characterId>` */
+    sub: string;
+    /** Character name. */
+    name?: string;
+    /** Granted scopes: a single string, or an array when more than one. */
+    scp?: string | string[];
+    /** Expiry as epoch seconds. */
+    exp?: number;
+    /** Issued-at as epoch seconds. */
+    iat?: number;
+    /** Owner hash; changes on character transfer. */
+    owner?: string;
+    iss?: string;
+    aud?: string | string[];
+    [claim: string]: unknown;
+}
+/** Identity and lifetime information extracted from an EVE SSO access token. */
+export interface DecodedAccessToken {
+    characterId: number;
+    characterName: string;
+    scopes: string[];
+    /** Epoch milliseconds, or undefined when the token carries no `exp`. */
+    expiresAt?: number;
+    ownerHash?: string;
+    claims: EveJwtClaims;
+}
+/**
+ * Decode the payload of a JWT without verifying its signature.
+ *
+ * Tokens reach the manager directly from SSO over TLS, so the payload is
+ * trusted for the purpose of learning which character it belongs to. Do not
+ * use this to authenticate tokens presented by third parties.
+ */
+export declare function decodeJwtPayload(token: string): EveJwtClaims;
+/** Parse the character id out of an SSO `sub` claim (`CHARACTER:EVE:123`). */
+export declare function parseCharacterId(sub: unknown): number;
+/** Normalise the `scp` claim, which SSO emits as a string for one scope and an array otherwise. */
+export declare function parseScopes(scp: unknown): string[];
+/** Decode an EVE SSO access token into the fields the token manager stores. */
+export declare function decodeAccessToken(token: string): DecodedAccessToken;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/auth/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AAEA,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,+BAA+B;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;CACtB;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAiB5D;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAWrD;AAED,mGAAmG;AACnG,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAQlD;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAWnE"}

package/dist/auth/pkce.d.mts

@@ -0,0 +1,21 @@
+/**
+ * A PKCE verifier/challenge pair for the authorization-code flow of a public
+ * client (one that cannot hold a client secret).
+ */
+export interface PkcePair {
+    /** Random secret sent with the token request as `code_verifier`. */
+    codeVerifier: string;
+    /** `BASE64URL(SHA256(codeVerifier))`, sent in the authorization URL. */
+    codeChallenge: string;
+    /** Always `S256`; EVE SSO does not accept the plain method. */
+    codeChallengeMethod: 'S256';
+}
+/** Generate a 32-byte base64url code verifier (43 characters). */
+export declare function generateCodeVerifier(): string;
+/** Derive the S256 code challenge for a verifier. */
+export declare function codeChallengeFromVerifier(codeVerifier: string): string;
+/** Generate a verifier and its challenge in one call. */
+export declare function generatePkcePair(): PkcePair;
+/** Generate an unguessable OAuth2 `state` value. */
+export declare function generateState(): string;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/auth/pkce.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A PKCE verifier/challenge pair for the authorization-code flow of a public
+ * client (one that cannot hold a client secret).
+ */
+export interface PkcePair {
+    /** Random secret sent with the token request as `code_verifier`. */
+    codeVerifier: string;
+    /** `BASE64URL(SHA256(codeVerifier))`, sent in the authorization URL. */
+    codeChallenge: string;
+    /** Always `S256`; EVE SSO does not accept the plain method. */
+    codeChallengeMethod: 'S256';
+}
+/** Generate a 32-byte base64url code verifier (43 characters). */
+export declare function generateCodeVerifier(): string;
+/** Derive the S256 code challenge for a verifier. */
+export declare function codeChallengeFromVerifier(codeVerifier: string): string;
+/** Generate a verifier and its challenge in one call. */
+export declare function generatePkcePair(): PkcePair;
+/** Generate an unguessable OAuth2 `state` value. */
+export declare function generateState(): string;
+//# sourceMappingURL=pkce.d.ts.map