dsh-plugin-subscription-oauth 0.0.0-stage → 0.1.0

package/lib/auth/tokens.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Access-token lifecycle for one provider's accounts.
+ *
+ * Every service issues short-lived access tokens, so a request resolves a
+ * usable token first: a token close to expiry is refreshed eagerly rather than
+ * after the request already failed. Concurrent resolutions share one in-flight
+ * refresh, so a burst of parallel requests cannot stampede the token endpoint.
+ *
+ * What a refresh *is* stays provider-owned — the manager takes a callback and
+ * persists whatever it returns.
+ *
+ * @module dsh-plugin-subscription-oauth/auth/tokens
+ */
+import type { SessionBase, TokenStore } from './store.js';
+/** Default refresh trigger: this long before expiry. */
+export declare const DEFAULT_PREEMPT_MS: number;
+/** One provider's token-endpoint answer, normalised. */
+export interface TokenSet {
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    /** Epoch milliseconds after which the access token must not be sent. */
+    readonly expiresAt: number;
+}
+/** A usable access token plus the account it belongs to. */
+export interface SessionToken {
+    readonly account: string;
+    readonly accessToken: string;
+    readonly expiresAt: number;
+}
+/** What the manager needs to resolve tokens for one provider. */
+export interface TokenManagerOptions<S extends SessionBase> {
+    readonly store: TokenStore<S>;
+    /** Human name used in failure messages, e.g. `Kimi Code`. */
+    readonly displayName: string;
+    /**
+     * Redeem one account's refresh token.
+     * @throws {ProviderError} with {@link REAUTH_REQUIRED} when the account must sign in again.
+     */
+    readonly refresh: (session: S) => Promise<TokenSet>;
+    /** Refresh when the token has less than this much life left. */
+    readonly preemptMs?: number;
+}
+/** Resolves and refreshes one provider's access tokens. */
+export declare class TokenManager<S extends SessionBase> {
+    private readonly options;
+    private readonly refreshes;
+    private readonly preemptMs;
+    constructor(options: TokenManagerOptions<S>);
+    /** Stored session for one account (default account when omitted). */
+    session(account?: string): Promise<{
+        account: string;
+        session: S;
+    } | undefined>;
+    /** Every stored account key. */
+    accounts(): Promise<string[]>;
+    /** The default account key, when one exists. */
+    defaultAccount(): Promise<string | undefined>;
+    /**
+     * Resolve a request-ready token for one account.
+     *
+     * @param account - account key; the default account is used when omitted.
+     * @param force - refresh even when the stored token still has life left.
+     * @returns the usable token.
+     * @throws {ProviderError} with {@link REAUTH_REQUIRED} when the account cannot be recovered.
+     */
+    resolve(account?: string, force?: boolean): Promise<SessionToken>;
+    /** Refresh one account, sharing one in-flight request per account. */
+    private refresh;
+}
+/**
+ * Fold a refreshed token set back onto the identity-bearing session fields.
+ * @param tokens - the refreshed tokens.
+ * @param previous - the session the refresh started from.
+ * @returns the session to persist.
+ */
+export declare function foldTokens<S extends SessionBase>(tokens: TokenSet, previous: S): S;

package/lib/auth/tokens.js

@@ -0,0 +1,103 @@
+/**
+ * Access-token lifecycle for one provider's accounts.
+ *
+ * Every service issues short-lived access tokens, so a request resolves a
+ * usable token first: a token close to expiry is refreshed eagerly rather than
+ * after the request already failed. Concurrent resolutions share one in-flight
+ * refresh, so a burst of parallel requests cannot stampede the token endpoint.
+ *
+ * What a refresh *is* stays provider-owned — the manager takes a callback and
+ * persists whatever it returns.
+ *
+ * @module dsh-plugin-subscription-oauth/auth/tokens
+ */
+import { REAUTH_REQUIRED, ProviderError } from '../errors.js';
+/** Default refresh trigger: this long before expiry. */
+export const DEFAULT_PREEMPT_MS = 5 * 60 * 1000;
+/** Resolves and refreshes one provider's access tokens. */
+export class TokenManager {
+    options;
+    refreshes = new Map();
+    preemptMs;
+    constructor(options) {
+        this.options = options;
+        this.preemptMs = options.preemptMs ?? DEFAULT_PREEMPT_MS;
+    }
+    /** Stored session for one account (default account when omitted). */
+    async session(account) {
+        const key = account ?? await this.options.store.defaultAccount();
+        if (key === undefined)
+            return undefined;
+        const session = await this.options.store.get(key);
+        return session === undefined ? undefined : { account: key, session };
+    }
+    /** Every stored account key. */
+    async accounts() {
+        return Object.keys(await this.options.store.list());
+    }
+    /** The default account key, when one exists. */
+    async defaultAccount() {
+        return this.options.store.defaultAccount();
+    }
+    /**
+     * Resolve a request-ready token for one account.
+     *
+     * @param account - account key; the default account is used when omitted.
+     * @param force - refresh even when the stored token still has life left.
+     * @returns the usable token.
+     * @throws {ProviderError} with {@link REAUTH_REQUIRED} when the account cannot be recovered.
+     */
+    async resolve(account, force = false) {
+        const found = await this.session(account);
+        if (found === undefined) {
+            throw new ProviderError(account === undefined
+                ? `no ${this.options.displayName} account is signed in`
+                : `${this.options.displayName} account ${account} is not signed in`, REAUTH_REQUIRED);
+        }
+        const { account: key, session } = found;
+        if (!force && Date.now() + this.preemptMs < session.expiresAt) {
+            return { account: key, accessToken: session.accessToken, expiresAt: session.expiresAt };
+        }
+        const refreshed = await this.refresh(key, session);
+        return { account: key, accessToken: refreshed.accessToken, expiresAt: refreshed.expiresAt };
+    }
+    /** Refresh one account, sharing one in-flight request per account. */
+    async refresh(key, session) {
+        const existing = this.refreshes.get(key);
+        if (existing !== undefined)
+            return existing;
+        const pending = (async () => {
+            if (session.refreshToken === undefined) {
+                throw new ProviderError(`${this.options.displayName} account ${key} has no refresh token; sign in again`, REAUTH_REQUIRED);
+            }
+            const tokens = await this.options.refresh(session);
+            const stored = await this.options.store.get(key);
+            if (stored === undefined) {
+                throw new ProviderError(`${this.options.displayName} account ${key} was removed while refreshing`, REAUTH_REQUIRED);
+            }
+            await this.options.store.save(key, foldTokens(tokens, stored), { makeDefault: false });
+            return tokens;
+        })();
+        this.refreshes.set(key, pending);
+        try {
+            return await pending;
+        }
+        finally {
+            this.refreshes.delete(key);
+        }
+    }
+}
+/**
+ * Fold a refreshed token set back onto the identity-bearing session fields.
+ * @param tokens - the refreshed tokens.
+ * @param previous - the session the refresh started from.
+ * @returns the session to persist.
+ */
+export function foldTokens(tokens, previous) {
+    return {
+        ...previous,
+        accessToken: tokens.accessToken,
+        expiresAt: tokens.expiresAt,
+        ...tokens.refreshToken === undefined ? {} : { refreshToken: tokens.refreshToken },
+    };
+}

package/lib/client/SubscriptionsSection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Subscriptions settings page.
+ *
+ * One card per provider route — Kimi Code, Grok (X Premium), Google Antigravity
+ * — describing that route's connection, accounts, and model catalog. Every fact
+ * arrives from the node half's `subscription-oauth` RPC endpoints, so this
+ * component holds no credential state of its own. The status poll runs only
+ * while a login is pending, so an idle page performs no requests.
+ *
+ * Colors resolve through `--dsw-alias-*` design tokens, so the page follows the
+ * active theme; every user-visible string goes through the locale-bound `t`.
+ *
+ * @module dsh-plugin-subscription-oauth/client/SubscriptionsSection
+ */
+import type { SubscriptionsKey } from './locales.js';
+import type { SubscriptionsCall } from './subscriptions-rpc.js';
+/** What the node half injects into this section. */
+export interface SubscriptionsSectionInjected {
+    /** Typed caller for the plugin's RPC endpoints. */
+    call: SubscriptionsCall;
+    /** Translate a key of this plugin's settings namespace. */
+    t: (key: SubscriptionsKey, params?: Record<string, unknown>) => string;
+}
+/** Component props: the shell supplies `close`, the plugin supplies the rest. */
+export type SubscriptionsSectionProps = Partial<SubscriptionsSectionInjected> & {
+    /** Close the settings panel (owned by the settings shell). */
+    close?: () => void;
+};
+/**
+ * The Subscriptions settings section.
+ * @param props - section props (inject face plus the shell's `close`).
+ * @returns the section content.
+ */
+export declare function SubscriptionsSection(props: SubscriptionsSectionProps): import("react").JSX.Element;