@tigeropenapi/tigeropen 0.5.5 → 0.5.7

package/dist/esm/auth/oauth2/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Categorized errors from OAuth 2.0 authorization flows.
+ *
+ * Authorization server error details are retained in the error message.
+ */
+/** Error category. Each one implies a different action. */
+export var OAuth2Category;
+(function (OAuth2Category) {
+    /** Cannot fetch authorization server metadata: wrong address, service down, no network */
+    OAuth2Category["MetadataUnavailable"] = "METADATA_UNAVAILABLE";
+    /** No usable client_id, and automatic registration is not possible */
+    OAuth2Category["ClientRegistrationRequired"] = "CLIENT_REGISTRATION_REQUIRED";
+    /** Callback stage failed: timeout, user denial, or state mismatch */
+    OAuth2Category["CallbackFailed"] = "CALLBACK_FAILED";
+    /**
+     * Device flow not approved in time, or explicitly denied. Kept separate from
+     * ReauthorizationRequired because only a new device authorization is needed -- the
+     * stored token was not touched.
+     */
+    OAuth2Category["DeviceAuthorizationFailed"] = "DEVICE_AUTHORIZATION_FAILED";
+    /** refresh_token expired, revoked, or never obtained. Retrying is pointless */
+    OAuth2Category["ReauthorizationRequired"] = "REAUTHORIZATION_REQUIRED";
+    /** Token endpoint call failed, and not in the terminal way above */
+    OAuth2Category["TokenRequestFailed"] = "TOKEN_REQUEST_FAILED";
+    /** Reading or writing the local token file failed */
+    OAuth2Category["StorageFailed"] = "STORAGE_FAILED";
+})(OAuth2Category || (OAuth2Category = {}));
+/** Thrown by any stage of the OAuth2 flow. */
+export class OAuth2Error extends Error {
+    constructor(category, message, cause) {
+        super(message);
+        this.name = 'OAuth2Error';
+        this.category = category;
+        this.cause = cause;
+    }
+    get reauthorizationRequired() {
+        return this.category === OAuth2Category.ReauthorizationRequired;
+    }
+    toString() {
+        return `OAuth2Error{${this.category}: ${this.message}}`;
+    }
+}
+/**
+ * A grant the authorization server refused.
+ *
+ * Carries the error code so a caller can tell a rejected credential from a rejected
+ * client registration. Its category is `ReauthorizationRequired`, so callers that only
+ * know the public type behave as they would for any terminal authorization failure.
+ */
+export class RejectedGrantError extends OAuth2Error {
+    constructor(error, description) {
+        super(OAuth2Category.ReauthorizationRequired, `token request rejected: ${error} ${description}`);
+        this.name = 'RejectedGrantError';
+        this.error = error;
+    }
+    get isClientRejected() {
+        return this.error === 'invalid_client';
+    }
+}

package/dist/esm/auth/oauth2/http-utils.js

@@ -0,0 +1,105 @@
+/**
+ * HTTP helpers for OAuth 2.0 JSON and form-encoded requests.
+ *
+ * OAuth error responses retain 4xx response bodies for protocol-level error handling.
+ */
+import { OAuth2Category, OAuth2Error } from './errors.js';
+/**
+ * Every call here is a small JSON exchange with the authorization server, so a request
+ * that has not answered in this long is not going to. Same values as the Java and
+ * Python SDKs.
+ */
+export const CONNECT_TIMEOUT_SECONDS = 5;
+export const READ_TIMEOUT_SECONDS = 10;
+/** Combined budget handed to `AbortSignal.timeout`; fetch does not split the two. */
+const REQUEST_TIMEOUT_MS = (CONNECT_TIMEOUT_SECONDS + READ_TIMEOUT_SECONDS) * 1000;
+const JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+const FORM_CONTENT_TYPE = 'application/x-www-form-urlencoded; charset=utf-8';
+function encodeForm(form) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(form)) {
+        if (value !== undefined && value !== null) {
+            params.append(key, value);
+        }
+    }
+    return params.toString();
+}
+export async function getJson(url) {
+    return execute('GET', url, undefined, undefined);
+}
+export async function postJson(url, payload) {
+    return execute('POST', url, JSON.stringify(payload), JSON_CONTENT_TYPE);
+}
+export async function postForm(url, form) {
+    return execute('POST', url, encodeForm(form), FORM_CONTENT_TYPE);
+}
+/**
+ * Post a form and return the HTTP status without requiring a response body.
+ *
+ * RFC 7009 revocation returns an empty success body, so no parsing is performed.
+ *
+ * @returns the HTTP status code
+ * @throws OAuth2Error on connection failure
+ */
+export async function postFormForStatus(url, form) {
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: { Accept: 'application/json', 'Content-Type': FORM_CONTENT_TYPE },
+            body: encodeForm(form),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        throw new OAuth2Error(OAuth2Category.TokenRequestFailed, `request fail: ${url}`, e);
+    }
+    return response.status;
+}
+/**
+ * Send the request and parse the response body as an object.
+ *
+ * A 4xx returns its body instead of throwing: OAuth2 errors (`invalid_grant`,
+ * `authorization_pending` and friends) live in the 4xx body, and the caller needs the
+ * `error` field to tell "wait and retry" from "re-authorize". Only a connection failure
+ * or a non-JSON response throws.
+ */
+async function execute(method, url, body, contentType) {
+    const headers = { Accept: 'application/json' };
+    if (contentType) {
+        headers['Content-Type'] = contentType;
+    }
+    let response;
+    try {
+        response = await fetch(url, {
+            method,
+            headers,
+            body,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        throw new OAuth2Error(OAuth2Category.MetadataUnavailable, `request fail: ${url}`, e);
+    }
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (e) {
+        throw new OAuth2Error(OAuth2Category.TokenRequestFailed, `cannot decode response from ${url}, http status ${response.status}`, e);
+    }
+    if (!text) {
+        throw new OAuth2Error(OAuth2Category.TokenRequestFailed, `empty response from ${url}, http status ${response.status}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        throw new OAuth2Error(OAuth2Category.TokenRequestFailed, `non-JSON response from ${url}, http status ${response.status}`, e);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new OAuth2Error(OAuth2Category.TokenRequestFailed, `unexpected response from ${url}, http status ${response.status}`);
+    }
+    return parsed;
+}

package/dist/esm/auth/oauth2/index.js

@@ -0,0 +1,11 @@
+/** OAuth 2.0 authentication, authorization flows, and token persistence. */
+export { OAuth2ClientRegistration } from './client-registration.js';
+export { OAuth2DeviceAuthorization, DEFAULT_DEVICE_INTERVAL_SECONDS } from './device-authorization.js';
+export { OAuth2Category, OAuth2Error, RejectedGrantError } from './errors.js';
+export { LoopbackReceiver, CALLBACK_PATH } from './loopback-receiver.js';
+export { OAuth2Metadata } from './metadata.js';
+export { OAuth2Authentication, BEARER_PREFIX } from './oauth2-authentication.js';
+export { OAuth2SessionManager, BUILTIN_ISSUER, CLIENT_NAME, DEFAULT_AUTHORIZE_TIMEOUT_SECONDS, DEFAULT_MANUAL_CALLBACK_PORT, DEFAULT_REFRESH_AHEAD_MILLIS, ENV_ISSUER, MIN_USABLE_REMAINING_MILLIS, } from './session-manager.js';
+export { OAuth2Token, TOKEN_SCHEMA_VERSION, currentMillis } from './token.js';
+export { OAuth2TokenStore, DEFAULT_SURFACE, ENV_HOME, hashIssuer } from './token-store.js';
+export { CONNECT_TIMEOUT_SECONDS, READ_TIMEOUT_SECONDS } from './http-utils.js';

package/dist/esm/auth/oauth2/loopback-receiver.js

@@ -0,0 +1,178 @@
+/**
+ * Single-use OAuth 2.0 loopback redirect receiver (RFC 8252).
+ *
+ * The receiver binds only to `127.0.0.1` to prevent authorization code exposure on the
+ * local network. Dynamic registration uses a system-assigned port as permitted by
+ * RFC 8252 §7.3; manual registration requires a port matching its redirect URI. The IP
+ * literal avoids the name-resolution risks described by RFC 8252 §8.3.
+ */
+import * as http from 'http';
+import { OAuth2Category, OAuth2Error } from './errors.js';
+export const CALLBACK_PATH = '/callback';
+/** Inline SVG avoids external resources and font-dependent glyph rendering. */
+function icon(color, path) {
+    return `<svg width='64' height='64' viewBox='0 0 64 64' aria-hidden='true'>`
+        + `<circle cx='32' cy='32' r='29' fill='none' stroke='${color}' stroke-width='4'/>`
+        + `<path d='${path}' fill='none' stroke='${color}' stroke-width='5'`
+        + ` stroke-linecap='round' stroke-linejoin='round'/></svg>`;
+}
+/** Green tick. */
+const ICON_SUCCESS = icon('#22c55e', 'M19 33l9.5 9.5L45 22');
+/** Grey dash for the normal `access_denied` outcome. */
+const ICON_CANCELLED = icon('#9ca3af', 'M20 32h24');
+/** Red cross, for outcomes that really are failures. */
+const ICON_FAILED = icon('#ef4444', 'M22 22l20 20M42 22L22 42');
+/** English callback text, kept consistent with the Java and Python SDKs. */
+const TEXT = {
+    title: 'Tiger OpenAPI',
+    success: ['Authorization successful', 'You can close this page and return to the application.'],
+    cancelled: ['Authorization cancelled', 'You declined this authorization. You can close this page.'],
+    failed: ['Authorization failed', 'Please return to the application and try again.'],
+};
+/** Classify `access_denied` as cancellation and other errors as failures. */
+function outcomeOf(params) {
+    if ('code' in params)
+        return 'success';
+    if (params['error'] === 'access_denied')
+        return 'cancelled';
+    return 'failed';
+}
+/**
+ * Render a redacted callback outcome page.
+ *
+ * Callback parameters, including authorization codes and errors, are omitted because
+ * browser history, screenshots, and extensions may expose page content. Full parameters
+ * remain available to internal callback processing.
+ */
+function renderPage(params) {
+    const outcome = outcomeOf(params);
+    const svg = { success: ICON_SUCCESS, cancelled: ICON_CANCELLED, failed: ICON_FAILED }[outcome];
+    const [heading, detail] = TEXT[outcome];
+    return `<!DOCTYPE html><html><head><meta charset='utf-8'>`
+        + `<meta name='viewport' content='width=device-width,initial-scale=1'>`
+        + `<title>${TEXT['title']}</title></head>`
+        + `<body style="margin:0;min-height:100vh;display:flex;align-items:center;`
+        + `justify-content:center;`
+        + `font-family:-apple-system,BlinkMacSystemFont,'PingFang SC','Microsoft YaHei',`
+        + `sans-serif;background:#fafafa;color:#1f2328">`
+        + `<main style='text-align:center;padding:48px 24px;max-width:420px'>`
+        + `${svg}`
+        + `<h2 style='margin:24px 0 8px;font-size:20px;font-weight:600'>${heading}</h2>`
+        + `<p style='margin:0;font-size:14px;line-height:1.6;color:#6b7280'>${detail}</p>`
+        + `</main></body></html>`;
+}
+/** Single-shot local callback server. */
+export class LoopbackReceiver {
+    constructor(server) {
+        this.port = 0;
+        this.params = {};
+        this.fired = false;
+        this.waiters = [];
+        this.server = server;
+    }
+    /**
+     * Bind the receiver. It must be listening before the authorization request is issued.
+     *
+     * @param port port to bind; 0 lets the system assign a free one
+     */
+    static async start(port = 0) {
+        const server = http.createServer();
+        const receiver = new LoopbackReceiver(server);
+        server.on('request', (req, res) => {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (url.pathname !== CALLBACK_PATH) {
+                res.writeHead(404, { 'Content-Length': '0' });
+                res.end();
+                return;
+            }
+            const snapshot = receiver.record(url.searchParams);
+            const body = Buffer.from(renderPage(snapshot), 'utf-8');
+            res.writeHead(200, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Content-Length': String(body.length),
+            });
+            res.end(body);
+            receiver.release(snapshot);
+        });
+        await new Promise((resolve, reject) => {
+            const onError = (e) => {
+                // A fixed port can conflict with another listener; system-assigned ports do not.
+                const hint = port === 0 ? '' : ` (port ${port} is in use; free it or set another callbackPort`
+                    + ' matching the redirect_uri registered for your client)';
+                reject(new OAuth2Error(OAuth2Category.CallbackFailed, `cannot bind loopback callback server on 127.0.0.1:${port}${hint}`, e));
+            };
+            server.once('error', onError);
+            server.listen(port, '127.0.0.1', () => {
+                server.removeListener('error', onError);
+                const address = server.address();
+                receiver.port = typeof address === 'object' && address ? address.port : port;
+                resolve();
+            });
+        });
+        return receiver;
+    }
+    get redirectUri() {
+        return `http://127.0.0.1:${this.port}${CALLBACK_PATH}`;
+    }
+    get boundPort() {
+        return this.port;
+    }
+    /**
+     * Wait for the browser callback.
+     *
+     * @returns the query parameters carried by the callback
+     * @throws OAuth2Error on timeout
+     */
+    waitForCallback(timeoutSeconds) {
+        if (this.fired) {
+            return Promise.resolve({ ...this.params });
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.waiters = this.waiters.filter((w) => w !== onParams);
+                reject(new OAuth2Error(OAuth2Category.CallbackFailed, 'waiting for authorization callback timed out'));
+            }, timeoutSeconds * 1000);
+            const onParams = (params) => {
+                clearTimeout(timer);
+                resolve(params);
+            };
+            this.waiters.push(onParams);
+        });
+    }
+    close() {
+        try {
+            // The browser keeps its connection alive after the redirect, and close() alone
+            // waits for it. That would hold the port -- which matters for the fixed port a
+            // manually registered client has to reuse on the next authorization.
+            this.server.closeAllConnections?.();
+        }
+        catch {
+            // Older runtimes have no such method; the idle timeout releases the port instead.
+        }
+        try {
+            this.server.close();
+        }
+        catch {
+            // Already closed; nothing to release.
+        }
+    }
+    /** Record the callback params (first one wins) and return a snapshot of them. */
+    record(search) {
+        if (!this.fired) {
+            for (const [key, value] of search.entries()) {
+                this.params[key] = value;
+            }
+        }
+        return { ...this.params };
+    }
+    release(snapshot) {
+        if (this.fired)
+            return;
+        this.fired = true;
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const waiter of waiters) {
+            waiter(snapshot);
+        }
+    }
+}

package/dist/esm/auth/oauth2/metadata.js

@@ -0,0 +1,30 @@
+/**
+ * Authorization server metadata (RFC 8414).
+ *
+ * Endpoints always come from metadata, never hardcoded, so switching environments only
+ * means changing the issuer.
+ */
+export class OAuth2Metadata {
+    constructor(init = {}) {
+        this.issuer = init.issuer;
+        this.authorizationEndpoint = init.authorizationEndpoint;
+        this.tokenEndpoint = init.tokenEndpoint;
+        this.registrationEndpoint = init.registrationEndpoint;
+        this.deviceAuthorizationEndpoint = init.deviceAuthorizationEndpoint;
+        this.revocationEndpoint = init.revocationEndpoint;
+        this.scopesSupported = init.scopesSupported ?? [];
+    }
+    static fromJSON(data) {
+        if (!data)
+            return null;
+        return new OAuth2Metadata({
+            issuer: data.issuer,
+            authorizationEndpoint: data.authorization_endpoint,
+            tokenEndpoint: data.token_endpoint,
+            registrationEndpoint: data.registration_endpoint,
+            deviceAuthorizationEndpoint: data.device_authorization_endpoint,
+            revocationEndpoint: data.revocation_endpoint,
+            scopesSupported: data.scopes_supported ?? [],
+        });
+    }
+}

package/dist/esm/auth/oauth2/oauth2-authentication.js

@@ -0,0 +1,70 @@
+/** Request authentication backed by an OAuth 2.0 session manager. */
+import { AuthenticationAttempt, AuthenticationType, RetryDecision, } from '../authentication.js';
+import { OAuth2Error } from './errors.js';
+export const BEARER_PREFIX = 'Bearer ';
+const UNAUTHORIZED_STATUS = 401;
+/** Authenticate with an OAuth2 access token. */
+export class OAuth2Authentication {
+    constructor(sessionManager) {
+        if (!sessionManager) {
+            throw new Error('OAuth2SessionManager is required');
+        }
+        this.sessions = sessionManager;
+    }
+    get authType() {
+        return AuthenticationType.OAuth2;
+    }
+    get sessionManager() {
+        return this.sessions;
+    }
+    /**
+     * Attach a Bearer token to the request context.
+     *
+     * Near-expiry refreshes use the session manager's single-flight synchronization.
+     * Missing authorization rejects with `ReauthorizationRequired` without starting an
+     * implicit browser flow.
+     */
+    async apply(context) {
+        const accessToken = await this.sessions.getAccessToken();
+        context.authorizationHeader = BEARER_PREFIX + accessToken;
+        return new AuthenticationAttempt(AuthenticationType.OAuth2, accessToken);
+    }
+    /**
+     * Process HTTP 401 responses.
+     *
+     * HTTP 403 indicates insufficient permission and cannot be resolved by refreshing a
+     * token with the same scope. Server errors and timeouts are not credential failures.
+     */
+    async onUnauthorized(attempt, statusCode) {
+        if (statusCode !== UNAUTHORIZED_STATUS) {
+            return RetryDecision.noRetry();
+        }
+        const credential = attempt?.credential;
+        try {
+            // Reuse a token already rotated elsewhere without another token request.
+            const refreshed = await this.sessions.refreshAfterUnauthorized(credential);
+            if (!refreshed || !refreshed.accessToken) {
+                return RetryDecision.noRetry();
+            }
+            if (credential !== undefined && refreshed.accessToken === credential) {
+                // Credential unchanged, so a retry would get the same 401.
+                return RetryDecision.noRetry();
+            }
+            return RetryDecision.retry(BEARER_PREFIX + refreshed.accessToken);
+        }
+        catch (e) {
+            if (!(e instanceof OAuth2Error)) {
+                // Not an OAuth2Error, so most likely a defect in the refresh path.
+                console.warn('[TigerOpen] oauth2 refresh after 401 error', e);
+            }
+            return RetryDecision.noRetry();
+        }
+    }
+    /**
+     * The session is owned by the application and may still be in use, so it is not
+     * closed here.
+     */
+    close() {
+        // Nothing to release.
+    }
+}