openlimiter 1.2.0 → 1.3.1

package/dist/hub-auth.js

@@ -0,0 +1,280 @@
+/**
+ * Signing in to the hub, staying signed in, and reading who is signed in.
+ *
+ * The device flow itself is nothing this build invented: a code and an
+ * address are shown, somebody types the code somewhere else, and this process
+ * polls until the hub says approved, denied or expired. The hub is the only
+ * clock that matters for expiry: it is the one thing that can say the device
+ * code has lapsed, so this build never guesses at a deadline of its own. The
+ * poll loop still carries a safety ceiling, derived from the hub's own stated
+ * lifetime, so a stubbed or misbehaving transport in a test cannot spin it
+ * forever.
+ */
+import { cliLoginPollRequest, cliLoginStartRequest, grantRenewRequest, hubConfigured, parseHubJson } from "./hub.js";
+import { sessionIsFresh } from "./session.js";
+/** The sentence a hub side revocation prints, word for word. */
+export const REVOKED_SENTENCE = "Signed out on the hub, run openlimiter login";
+/** The sentence a login code the hub already consumed prints, word for word. */
+export const CODE_CONSUMED_SENTENCE = "That code was already used, run openlimiter login again";
+/** Extra polls past the hub's own stated lifetime, before this build gives up. */
+export const LOGIN_SAFETY_MARGIN_POLLS = 5;
+function isFiniteInRange(value, minimum, maximum) {
+    return typeof value === "number" && Number.isFinite(value) && value >= minimum && value <= maximum;
+}
+function isBoundedString(value, minimum, maximum) {
+    return typeof value === "string" && value.length >= minimum && value.length <= maximum;
+}
+function isInstant(value) {
+    return isBoundedString(value, 1, 64) && Number.isFinite(Date.parse(value));
+}
+/**
+ * Whether Ctrl C asked this poll loop to stop.
+ *
+ * A plain `signal?.aborted === true` reads fine once, but TypeScript narrows
+ * that exact expression across the loop body, so a second identical check
+ * after an `await` is seen as comparing an already narrowed `false` against
+ * `true` and refused as unreachable. A function call has no such memory.
+ */
+export function isAborted(signal) {
+    return signal !== undefined && signal.aborted;
+}
+/** Parse the device flow's opening answer, trusting nothing about its shape. */
+export function parseLoginStart(body) {
+    const parsed = parseHubJson(body);
+    if (parsed === null)
+        return null;
+    const userCode = parsed["user_code"];
+    const deviceCode = parsed["device_code"];
+    const verificationUrl = parsed["verification_url"];
+    const interval = parsed["interval"];
+    const expiresIn = parsed["expires_in"];
+    if (!isBoundedString(userCode, 1, 64) ||
+        !isBoundedString(deviceCode, 1, 256) ||
+        !isBoundedString(verificationUrl, 8, 512) ||
+        !verificationUrl.startsWith("https://") ||
+        !isFiniteInRange(interval, 1, 300) ||
+        !isFiniteInRange(expiresIn, 1, 86_400)) {
+        return null;
+    }
+    return {
+        userCode,
+        deviceCode,
+        verificationUrl,
+        intervalSeconds: interval,
+        expiresInSeconds: expiresIn
+    };
+}
+/** Parse one poll answer, in the five shapes the contract allows. */
+export function parseLoginPoll(body) {
+    const parsed = parseHubJson(body);
+    if (parsed === null)
+        return null;
+    const status = parsed["status"];
+    if (status === "pending" ||
+        status === "slow_down" ||
+        status === "denied" ||
+        status === "expired" ||
+        status === "consumed") {
+        return { status };
+    }
+    if (status !== "approved")
+        return null;
+    const token = parsed["token"];
+    const expiresAt = parsed["expires_at"];
+    const refreshCredential = parsed["refresh_credential"];
+    const refreshExpiresAt = parsed["refresh_expires_at"];
+    const deviceId = parsed["device_id"];
+    if (!isBoundedString(token, 16, 32_768) ||
+        !isInstant(expiresAt) ||
+        !isBoundedString(refreshCredential, 16, 4_096) ||
+        !isInstant(refreshExpiresAt) ||
+        !isBoundedString(deviceId, 1, 128)) {
+        return null;
+    }
+    return { status: "approved", token, expiresAt, refreshCredential, refreshExpiresAt, deviceId };
+}
+/** Parse a renewal answer: a fresh token and a rotated refresh credential. */
+export function parseGrantRenewal(body) {
+    const parsed = parseHubJson(body);
+    if (parsed === null)
+        return null;
+    const token = parsed["token"];
+    const expiresAt = parsed["expires_at"];
+    const refreshCredential = parsed["refresh_credential"];
+    const refreshExpiresAt = parsed["refresh_expires_at"];
+    if (!isBoundedString(token, 16, 32_768) ||
+        !isInstant(expiresAt) ||
+        !isBoundedString(refreshCredential, 16, 4_096) ||
+        !isInstant(refreshExpiresAt)) {
+        return null;
+    }
+    return { token, expiresAt, refreshCredential, refreshExpiresAt };
+}
+function base64UrlDecode(segment) {
+    if (segment.length === 0 || segment.length > 16_384 || !/^[A-Za-z0-9_-]+$/u.test(segment)) {
+        return null;
+    }
+    try {
+        return Buffer.from(segment, "base64url").toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A human name for the account, read from the token if it carries one.
+ *
+ * The hub contract names no account label field at all, and a token is the
+ * one thing the approved answer definitely carries that could hold one: a
+ * JSON Web Token's own payload, unsigned and unverified here because nothing
+ * downstream trusts this label for anything but display. A token that is not
+ * a JWT, or carries no email claim, falls back to the device id, which is
+ * always there and is at least a stable name to look at with `whoami`.
+ */
+export function accountLabelFromToken(token, fallback) {
+    const segments = token.split(".");
+    if (segments.length !== 3)
+        return fallback;
+    const payload = segments[1];
+    if (payload === undefined)
+        return fallback;
+    const decoded = base64UrlDecode(payload);
+    if (decoded === null)
+        return fallback;
+    try {
+        const parsed = JSON.parse(decoded);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            const email = parsed["email"];
+            if (typeof email === "string" && email.length > 0 && email.length <= 256)
+                return email;
+        }
+    }
+    catch {
+        /* Not a JWT this build can read the claims of. The device id still names it. */
+    }
+    return fallback;
+}
+/**
+ * Run the whole device flow: start, show the code, poll until an ending.
+ *
+ * `slow_down` widens the interval rather than being treated as a failure,
+ * which is the device flow's own documented way of saying "you are polling
+ * this endpoint too often". A poll that could not be sent or read is not
+ * treated as `denied` either: a network blip inside a three minute window is
+ * routine, and the loop tries again next interval rather than ending the
+ * whole sign in over it.
+ */
+export async function runDeviceLogin(options) {
+    if (!hubConfigured(options.environment))
+        return { kind: "not_configured" };
+    const startRequest = cliLoginStartRequest(options.environment);
+    if (startRequest === null)
+        return { kind: "not_configured" };
+    let startReply;
+    try {
+        startReply = await options.transport(startRequest);
+    }
+    catch {
+        return { kind: "error", message: "could not reach the hub" };
+    }
+    if (startReply.status < 200 || startReply.status >= 300) {
+        return { kind: "error", message: "the hub refused the sign in request" };
+    }
+    const start = parseLoginStart(startReply.body);
+    if (start === null) {
+        return { kind: "error", message: "the hub answered with something this build could not read" };
+    }
+    options.emit("Enter this code: " + start.userCode);
+    options.emit("At: " + start.verificationUrl);
+    if (options.open)
+        options.openBrowser?.(start.verificationUrl);
+    let intervalSeconds = start.intervalSeconds;
+    const maxAttempts = Math.ceil(start.expiresInSeconds / intervalSeconds) + LOGIN_SAFETY_MARGIN_POLLS;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        if (isAborted(options.interruptSignal))
+            return { kind: "cancelled" };
+        await options.sleep(intervalSeconds * 1_000);
+        if (isAborted(options.interruptSignal))
+            return { kind: "cancelled" };
+        const pollRequest = cliLoginPollRequest(options.environment, start.deviceCode);
+        if (pollRequest === null)
+            return { kind: "error", message: "the device code could not be sent" };
+        let pollReply;
+        try {
+            pollReply = await options.transport(pollRequest);
+        }
+        catch {
+            continue;
+        }
+        if (pollReply.status < 200 || pollReply.status >= 300)
+            continue;
+        const poll = parseLoginPoll(pollReply.body);
+        if (poll === null)
+            continue;
+        if (poll.status === "pending")
+            continue;
+        if (poll.status === "slow_down") {
+            intervalSeconds += 5;
+            continue;
+        }
+        if (poll.status === "denied")
+            return { kind: "denied" };
+        if (poll.status === "expired")
+            return { kind: "expired" };
+        if (poll.status === "consumed")
+            return { kind: "expired", message: CODE_CONSUMED_SENTENCE };
+        const session = {
+            version: 1,
+            token: poll.token,
+            expiresAt: poll.expiresAt,
+            refreshCredential: poll.refreshCredential,
+            refreshExpiresAt: poll.refreshExpiresAt,
+            deviceId: poll.deviceId,
+            accountLabel: accountLabelFromToken(poll.token, poll.deviceId)
+        };
+        return { kind: "signed_in", session };
+    }
+    return { kind: "expired" };
+}
+/**
+ * Make sure a session is good for one more upload, renewing if it is not.
+ *
+ * A session inside the renewal window is used exactly as it stands: renewing
+ * early for no reason spends the one time use refresh credential for nothing.
+ * A 401 from the renewal call is read as the hub having revoked this device,
+ * never as an ordinary network failure, because the two need different
+ * endings: one clears the session and asks for a fresh sign in, the other
+ * leaves the session in place and lets the next attempt try again.
+ */
+export async function ensureFreshSession(session, now, environment, transport) {
+    if (sessionIsFresh(session, now))
+        return { kind: "fresh", session };
+    const request = grantRenewRequest(environment, session.refreshCredential);
+    if (request === null)
+        return { kind: "error" };
+    let reply;
+    try {
+        reply = await transport(request);
+    }
+    catch {
+        return { kind: "error" };
+    }
+    if (reply.status === 401)
+        return { kind: "revoked" };
+    if (reply.status < 200 || reply.status >= 300)
+        return { kind: "error" };
+    const renewal = parseGrantRenewal(reply.body);
+    if (renewal === null)
+        return { kind: "error" };
+    return {
+        kind: "renewed",
+        session: {
+            ...session,
+            token: renewal.token,
+            expiresAt: renewal.expiresAt,
+            refreshCredential: renewal.refreshCredential,
+            refreshExpiresAt: renewal.refreshExpiresAt
+        }
+    };
+}
+//# sourceMappingURL=hub-auth.js.map

package/dist/hub-auth.js.map

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

package/dist/hub-sync.d.ts

@@ -0,0 +1,144 @@
+import { type Snapshot } from "@openlimiter/core";
+import { type HubTransport } from "./hub.js";
+export declare const SYNC_CURSOR_FILE_NAME = "openlimiter-sync-cursor.json";
+/** The contract version this build speaks, and nothing else. */
+export declare const SYNC_SCHEMA_VERSION = 2;
+/**
+ * What this build calls itself on the wire.
+ *
+ * A constant, not a read of `package.json`: this module ships inside a
+ * published package, and a runtime file read is one more thing that can fail
+ * inside a command a status line depends on. See `acquire/identity.ts` in the
+ * core package for the same choice, made for the same reason.
+ */
+export declare const SYNC_CLIENT_VERSION = "1.3.1";
+/** Most rows one envelope may carry, usage and spend counted together. */
+export declare const SYNC_MAX_ROWS = 128;
+/** How long an unresolved upload may still be retried as itself. */
+export declare const SYNC_RESUME_WINDOW_HOURS = 23;
+export interface UsageSample {
+    readonly account_id: string;
+    readonly provider: string;
+    readonly meter: string;
+    readonly window_id: string;
+    readonly usage_percent: number;
+    readonly reset_at: string | null;
+    readonly observed_at: string;
+    readonly stale: boolean;
+}
+export interface ForecastInput {
+    readonly first_observed_at: string;
+    readonly last_observed_at: string;
+    readonly sample_count: number;
+    readonly burn_usd_per_day: number;
+}
+export interface ApiSpendSample {
+    readonly source_id: string;
+    readonly account_id: string;
+    readonly provider: string;
+    readonly key_label: string;
+    readonly month: string;
+    readonly spend_usd: number;
+    readonly budget_usd: number | null;
+    readonly source_period: readonly [string, string];
+    readonly currency_source: string;
+    readonly raw_unit_scale: number;
+    readonly forecast_date: string | null;
+    readonly forecast_input: ForecastInput | null;
+    readonly period_complete: boolean;
+}
+export interface SyncEnvelope {
+    readonly event_id: string;
+    readonly device_id: string;
+    readonly previous_sequence: number;
+    readonly sequence: number;
+    readonly observed_at: string;
+    readonly client_version: string;
+    readonly schema_version: number;
+    readonly usage_samples: readonly UsageSample[];
+    readonly api_spend_samples: readonly ApiSpendSample[];
+}
+/**
+ * Every usage row this device would upload, from the cache it already writes
+ * for the terminal and the tray.
+ *
+ * Only `PERCENT` rows are usage: a credit or token count is not a usage
+ * fraction and does not belong beside one. `API_BUDGET_PERCENT` is excluded
+ * too, porting the same rule `usage_samples_from_cache` in account.rs reads
+ * its own cache by: it is a budget reading at PERCENT unit, not a usage
+ * window, and sending it is exactly what gets a whole envelope rejected
+ * rather than the one row dropped, since the hub does not recognise it as
+ * usage at all. The Rust reader excludes the Moonshot provider by name too,
+ * as a second, belt and suspenders check; nothing here reproduces that one,
+ * because it cannot fire on this side of the boundary. Moonshot's own budget
+ * reading already carries provider `KIMI` in this build's own vocabulary
+ * (`PROVIDER_CODES` in types.ts has no `MOONSHOT` at all, and
+ * `normalizeMeter` refuses the whole reading for any provider string outside
+ * that set before a `Snapshot` is ever built), so the meter check above is
+ * this side's whole answer, not half of one. A row that fails a bound,
+ * including an unreadable account id, is dropped rather than repaired,
+ * matching the same rule the desktop reads its own cache by.
+ */
+export declare function usageSamplesFromSnapshots(snapshots: readonly Snapshot[], now: string): UsageSample[];
+/**
+ * Every spend row the cache has enough to build.
+ *
+ * This build tracks a point in time reading, not a month to date total with a
+ * forecast: those live in the desktop's dedicated spend engine, which this
+ * package does not have. So every row this function builds states its period
+ * honestly as "the start of this month through the moment of this upload"
+ * and never claims a forecast or a completed period it did not compute.
+ * `usedAmount`, `limitAmount` and `currency` travel together or not at all
+ * (see `Snapshot` in the core package), which is what this reads as "the
+ * cache has one".
+ */
+/** The providers the hub accepts an API spend sample for (mirrors API_PROVIDERS in the server contract); every other provider's spend stays local, otherwise one row would void the whole envelope. */
+export declare const SYNC_API_SPEND_PROVIDERS: ReadonlySet<string>;
+export declare function apiSpendSamplesFromSnapshots(snapshots: readonly Snapshot[], envelopeObservedAt: string): ApiSpendSample[];
+export interface EnvelopeIdentity {
+    readonly deviceId: string;
+    readonly eventId: string;
+    readonly previousSequence: number;
+    readonly observedAt: string;
+}
+/**
+ * One envelope from one set of readings.
+ *
+ * A reading observed after the envelope itself, which a clock stepping
+ * backwards between the cache write and this call would produce, is pulled
+ * back to the envelope's own timestamp rather than dropped. See
+ * `build_envelope` in `account.rs` for the same rule.
+ */
+export declare function buildSyncEnvelope(identity: EnvelopeIdentity, usageSamples: readonly UsageSample[], apiSpendSamples: readonly ApiSpendSample[]): SyncEnvelope;
+export interface RunSyncOptions {
+    readonly directory: string;
+    readonly environment: Readonly<Record<string, string | undefined>>;
+    readonly transport: HubTransport;
+    readonly now: string;
+    readonly token: string;
+    readonly deviceId: string;
+    readonly snapshots: readonly Snapshot[];
+}
+export type SyncResult = {
+    readonly kind: "nothing_to_sync";
+} | {
+    readonly kind: "accepted";
+    readonly rows: number;
+    readonly tier: string | null;
+} | {
+    readonly kind: "revoked";
+} | {
+    readonly kind: "rejected";
+} | {
+    readonly kind: "unavailable";
+};
+/**
+ * One upload, on the version 2 contract, with the same three way ending the
+ * hub's cursor rule requires: accepted advances the cursor, a reply that
+ * never arrived leaves the same upload pending for the next run, and a
+ * conflict names the hub's own sequence and is retried once.
+ */
+export declare function runSync(options: RunSyncOptions): Promise<SyncResult>;
+/** The state directory's default, exported so a caller need not repeat it. */
+export declare function defaultSyncDirectory(): string;
+//# sourceMappingURL=hub-sync.d.ts.map

package/dist/hub-sync.d.ts.map

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