vpndetection 5.0.0 → 5.2.0

package/dist/oauth.js

@@ -0,0 +1,240 @@
+import { oauthDeviceAuthorization, oauthMetadata, oauthRevoke, oauthToken, } from './generated/sdk.gen.js';
+import { errorFromResponse, OauthError, oauthErrorFrom, OauthExpiredTokenError, VPNDetectionError, } from './errors.js';
+import { asError, deadline, withRetry } from './transport.js';
+/**
+ * Signs a person in on their own machine with the OAuth device flow, so a
+ * program can be handed one of their API keys instead of asking them to paste
+ * it. Reached through `client.oauth`.
+ *
+ * Every call takes a client ID, issued on request from support@vpndetection.io.
+ * None of these requests carries the client's API key, and none needs one.
+ */
+export class OauthApi {
+    client;
+    retries;
+    timeoutMs;
+    // The poll's wait and its deadline, which tests replace together.
+    clock = { now: () => performance.now(), sleep: sleep };
+    constructor(client, retries, timeoutMs) {
+        this.client = client;
+        this.retries = retries;
+        this.timeoutMs = timeoutMs;
+    }
+    async metadata(options = {}) {
+        return withRetry(this.retries, async () => {
+            const res = await deadline(options.timeoutMs ?? this.timeoutMs, (signal) => oauthMetadata({
+                client: this.client, signal: signal,
+            }));
+            return decode(res, METADATA);
+        });
+    }
+    /**
+     * Start a device sign-in: show the person `user_code` and `verification_uri`,
+     * then hand the answer to `pollDeviceToken`. It consumes nothing, so it is
+     * retried like a lookup; a refusal such as `slow_down` is an `OauthError`.
+     */
+    async deviceAuthorization(clientId, options = {}) {
+        const body = {
+            client_id: clientId,
+            scope: options.scope || undefined,
+            resource: options.resource || undefined,
+        };
+        const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+        return withRetry(this.retries, async () => {
+            const res = await deadline(timeoutMs, (signal) => oauthDeviceAuthorization({
+                client: this.client, body: body, signal: signal,
+            }));
+            return decode(res, DEVICE_AUTHORIZATION);
+        });
+    }
+    /**
+     * Ask once whether the person has approved a device sign-in. Until they do,
+     * it rejects with an `OauthError` coded `authorization_pending`;
+     * `pollDeviceToken` is the loop around it.
+     *
+     * Never retried: an approved code is spent by the answer carrying the tokens,
+     * so a retry after a lost response could only lose them.
+     */
+    async exchangeDeviceCode(clientId, deviceCode, options = {}) {
+        return this.exchange({
+            grant_type: DEVICE_CODE_GRANT, device_code: deviceCode, client_id: clientId,
+        }, options.timeoutMs);
+    }
+    /**
+     * Trade a refresh token for a new pair. The old one is spent whatever happens
+     * next, so this is never retried. A refresh names the key the person picked
+     * (`apikey_id`) but never reveals it again (`apikey`).
+     */
+    async exchangeRefreshToken(clientId, refreshToken, options = {}) {
+        return this.exchange({
+            grant_type: 'refresh_token', refresh_token: refreshToken, client_id: clientId,
+        }, options.timeoutMs);
+    }
+    /**
+     * End a token. A refresh token ends the whole sign-in and every token it
+     * issued, which is how a program signs the machine out; an access token ends
+     * only itself. The server answers the same for any token, known or not.
+     */
+    async revoke(clientId, token, options = {}) {
+        await withRetry(this.retries, async () => {
+            const res = await deadline(options.timeoutMs ?? this.timeoutMs, (signal) => oauthRevoke({
+                client: this.client,
+                body: { token: token, client_id: clientId },
+                // The answer says nothing, so it is read as text and dropped rather than parsed.
+                parseAs: 'text',
+                signal: signal,
+            }));
+            throwIfFailed(res);
+        });
+    }
+    /**
+     * Wait for the person to approve a device sign-in, and return its tokens.
+     *
+     * Waits `device.interval` seconds (5 when that is below 1) before EVERY
+     * request, the first included, and 5 more for the rest of the call each time
+     * the server answers `slow_down`. Ends at the first answer that is neither:
+     * a denial rejects with `OauthAccessDeniedError`, a code that ran out with
+     * `OauthExpiredTokenError` - as does outliving `device.expires_in`, counted
+     * from this call, with no `status` - and any other failure as it came.
+     */
+    async pollDeviceToken(clientId, device, options = {}) {
+        let interval = device.interval >= 1 ? device.interval : 5;
+        const expires = this.clock.now() + device.expires_in * 1000;
+        for (;;) {
+            await this.clock.sleep(interval * 1000, options.signal);
+            if (this.clock.now() >= expires) {
+                throw new OauthExpiredTokenError();
+            }
+            try {
+                return await this.exchange({
+                    grant_type: DEVICE_CODE_GRANT, device_code: device.device_code, client_id: clientId,
+                }, options.timeoutMs, options.signal);
+            }
+            catch (err) {
+                if (!(err instanceof OauthError)) {
+                    throw err;
+                }
+                // RFC 8628: slow_down widens the interval for every later request, not just the next.
+                if (err.errorCode === 'slow_down') {
+                    interval += 5;
+                }
+                else if (err.errorCode !== 'authorization_pending') {
+                    throw err;
+                }
+            }
+        }
+    }
+    async exchange(form, timeoutMs, cancel) {
+        const res = await deadline(timeoutMs ?? this.timeoutMs, (signal) => oauthToken({
+            client: this.client, body: form, signal: signal,
+        }), cancel);
+        return decode(res, TOKEN_RESPONSE);
+    }
+}
+const DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const METADATA = {
+    issuer: { type: 'string', required: true },
+    authorization_endpoint: { type: 'string', required: true },
+    token_endpoint: { type: 'string', required: true },
+    device_authorization_endpoint: { type: 'string' },
+    revocation_endpoint: { type: 'string' },
+    scopes_supported: { type: 'string[]' },
+    response_types_supported: { type: 'string[]' },
+    grant_types_supported: { type: 'string[]' },
+    code_challenge_methods_supported: { type: 'string[]' },
+    token_endpoint_auth_methods_supported: { type: 'string[]' },
+    authorization_response_iss_parameter_supported: { type: 'boolean' },
+    service_documentation: { type: 'string' },
+};
+const DEVICE_AUTHORIZATION = {
+    device_code: { type: 'string', required: true },
+    user_code: { type: 'string', required: true },
+    verification_uri: { type: 'string', required: true },
+    verification_uri_complete: { type: 'string' },
+    expires_in: { type: 'number', required: true },
+    interval: { type: 'number', required: true },
+};
+const TOKEN_RESPONSE = {
+    access_token: { type: 'string', required: true },
+    token_type: { type: 'string', required: true },
+    expires_in: { type: 'number', required: true },
+    refresh_token: { type: 'string' },
+    scope: { type: 'string' },
+    apikey_id: { type: 'string', wire: 'mslm:apikey_id' },
+    apikey: { type: 'string', wire: 'mslm:apikey' },
+};
+// Only the declared members are copied, on PRESENCE, so an absent one stays
+// absent and an empty `scope` stays present. Anything else the server sends is
+// dropped rather than surfaced untyped.
+function decode(res, members) {
+    const status = throwIfFailed(res).status;
+    if (res.error !== undefined) {
+        // A 2xx the generated client could not parse, which reports it here.
+        throw asError(res.error);
+    }
+    const body = res.data;
+    if (!isObject(body)) {
+        throw new VPNDetectionError('server_error', 'the answer was not a JSON object', status);
+    }
+    const out = {};
+    for (const [name, member] of Object.entries(members)) {
+        const wire = member.wire ?? name;
+        const value = body[wire];
+        if (value === undefined || value === null) {
+            if (member.required) {
+                throw new VPNDetectionError('server_error', `the answer carried no ${wire}`, status);
+            }
+            continue;
+        }
+        if (!hasType(value, member.type)) {
+            throw new VPNDetectionError('server_error', `the answer's ${wire} is not a ${member.type}`, status);
+        }
+        out[name] = value;
+    }
+    return out;
+}
+// Only a 4xx whose body is a JSON object with a STRING `error` is an OAuth
+// refusal. Every 5xx, whatever it says, is the server failing, and is retried
+// wherever the operation retries.
+function throwIfFailed(res) {
+    if (res.response === undefined) {
+        throw new VPNDetectionError('network', 'no response from the API');
+    }
+    const { status, ok, headers } = res.response;
+    if (ok) {
+        return res.response;
+    }
+    const body = res.error;
+    if (status >= 400 && status < 500 && isObject(body) && typeof body.error === 'string') {
+        const description = typeof body.error_description === 'string' ? body.error_description : undefined;
+        throw oauthErrorFrom(body.error, description, status);
+    }
+    throw errorFromResponse(status, headers, body);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasType(value, type) {
+    if (type === 'string[]') {
+        return Array.isArray(value) && value.every((item) => typeof item === 'string');
+    }
+    return typeof value === type;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,18 @@
+import { VPNDetectionError } from './errors.js';
+export interface Res {
+    data?: unknown;
+    error?: unknown;
+    response?: Response;
+}
+export declare function unwrap<T>(res: Res): T;
+/**
+ * Bound one attempt, and report an expiry as our own error rather than the
+ * runtime's `TimeoutError`, whose message says nothing about which call gave up.
+ *
+ * The signal is built per call, so a retried request gets a fresh budget - the
+ * same per-attempt semantics the Go and Python clients have. Aborting `cancel`
+ * ends the attempt at once, rejecting with its reason.
+ */
+export declare function deadline<T>(timeoutMs: number, fn: (signal: AbortSignal) => Promise<T>, cancel?: AbortSignal): Promise<T>;
+export declare function withRetry<T>(retries: number, fn: () => Promise<T>): Promise<T>;
+export declare function asError(err: unknown): VPNDetectionError;

package/dist/transport.js

@@ -0,0 +1,82 @@
+import pRetry from 'p-retry';
+import { errorFromResponse, VPNDetectionError } from './errors.js';
+export function unwrap(res) {
+    if (res.response === undefined) {
+        throw new VPNDetectionError('network', 'no response from the API');
+    }
+    if (!res.response.ok) {
+        throw errorFromResponse(res.response.status, res.response.headers, res.error ?? res.data);
+    }
+    return res.data;
+}
+/**
+ * Bound one attempt, and report an expiry as our own error rather than the
+ * runtime's `TimeoutError`, whose message says nothing about which call gave up.
+ *
+ * The signal is built per call, so a retried request gets a fresh budget - the
+ * same per-attempt semantics the Go and Python clients have. Aborting `cancel`
+ * ends the attempt at once, rejecting with its reason.
+ */
+export async function deadline(timeoutMs, fn, cancel) {
+    cancel?.throwIfAborted();
+    const controller = new AbortController();
+    let timer;
+    let stop;
+    // Raced, not left to the signal alone: aborting releases the socket, but only
+    // a transport that HONORS the signal then settles, and a substituted `fetch`
+    // need not. Clearing the timer stops the losing side rejecting into nothing.
+    const expiry = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new VPNDetectionError('network', `request timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        if (cancel !== undefined) {
+            stop = () => {
+                controller.abort(cancel.reason);
+                reject(cancel.reason);
+            };
+            cancel.addEventListener('abort', stop, { once: true });
+        }
+    });
+    try {
+        return await Promise.race([fn(controller.signal), expiry]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (stop !== undefined) {
+            cancel?.removeEventListener('abort', stop);
+        }
+    }
+}
+// p-retry owns the backoff schedule; the extra sleep here is what honors a
+// server-supplied Retry-After, which p-retry has no way to know about. A 429
+// carrying that header is the only 429 worth retrying, which is why the wait
+// and the retry decision both key off the same field.
+export async function withRetry(retries, fn) {
+    try {
+        return await pRetry(fn, {
+            retries: retries,
+            shouldRetry: ({ error }) => !(error instanceof VPNDetectionError) || error.retryable,
+            onFailedAttempt: async ({ error }) => {
+                const seconds = error instanceof VPNDetectionError ? error.retryAfterSeconds : undefined;
+                if (seconds !== undefined && seconds > 0) {
+                    await new Promise((r) => setTimeout(r, seconds * 1000));
+                }
+            },
+        });
+    }
+    catch (err) {
+        throw asError(err);
+    }
+}
+export function asError(err) {
+    if (err instanceof VPNDetectionError) {
+        return err;
+    }
+    const cause = err?.cause;
+    if (cause instanceof VPNDetectionError) {
+        return cause;
+    }
+    return new VPNDetectionError('network', err instanceof Error ? err.message : String(err));
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vpndetection",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "Official Node.js client library for the VPNDetection API. Detect VPNs, proxies, Tor, hosting and CDN IPs.",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,7 @@
   },
   "devDependencies": {
     "@hey-api/openapi-ts": "^0.99.0",
-    "@mslmio/eslint-config": "^1.0.0",
+    "@mslmio/eslint-config": "^1.0.1",
     "@types/node": "^26.2.0",
     "eslint": "^9.39.0",
     "typescript": "^5.9.3"