dsh-plugin-subscription-oauth 0.2.1 → 0.3.0

package/lib/auth/ark-control.js

@@ -0,0 +1,304 @@
+/**
+ * The Ark control plane: STS credentials, request signing, and allowance reads.
+ *
+ * Ark splits its API in two. The **data plane** (`ark.cn-beijing.volces.com`)
+ * takes a plan API key as a plain bearer. The **control plane**
+ * (`ark.cn-beijing.volcengineapi.com`) is Volcengine OpenAPI: every call is
+ * `POST /?Action=<name>&Version=<date>` signed with the temporary AK/SK the SSO
+ * identity was exchanged for, and the plan's allowance lives only there.
+ *
+ * The signing below was written from the official CLI's own algorithm and then
+ * checked against the live service with real credentials, which answered 200 with
+ * the same body the CLI reports.
+ *
+ * @module dsh-plugin-subscription-oauth/auth/ark-control
+ */
+import { createHash, createHmac } from 'node:crypto';
+import { attributedHeaders } from './headers.js';
+/** Control-plane host: the OpenAPI endpoint, not the data-plane one. */
+export const ARK_CONTROL_HOST = 'ark.cn-beijing.volcengineapi.com';
+/** Region every Ark OpenAPI action is scoped to. */
+export const ARK_CONTROL_REGION = 'cn-beijing';
+/** Service name in the signing scope. */
+export const ARK_CONTROL_SERVICE = 'ark';
+/** Version every Ark OpenAPI action takes. */
+export const ARK_CONTROL_VERSION = '2024-01-01';
+/** An RFC 3339 UTC instant in the compact form the signature wants. */
+function amzDate(at) {
+    return at.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+}
+/** HMAC-SHA256 of `value` under `key`. */
+function hmac(key, value) {
+    return createHmac('sha256', key).update(value).digest();
+}
+/**
+ * Sign one OpenAPI request the way Volcengine expects.
+ *
+ * The canonical request lists `content-type;host;x-content-sha256;x-date`, which is
+ * the set the official client signs for these actions.
+ *
+ * @param input - method, query, body, and the credentials to sign with.
+ * @returns the headers to send.
+ */
+export function signArkRequest(input) {
+    const contentType = input.contentType ?? 'application/x-www-form-urlencoded';
+    const at = input.at ?? new Date();
+    const xDate = amzDate(at);
+    const contentSha = createHash('sha256').update(input.body).digest('hex');
+    const signedHeaders = 'content-type;host;x-content-sha256;x-date';
+    const canonical = [
+        input.method,
+        '/',
+        input.query,
+        `content-type:${contentType}`,
+        `host:${ARK_CONTROL_HOST}`,
+        `x-content-sha256:${contentSha}`,
+        `x-date:${xDate}`,
+        '',
+        signedHeaders,
+        contentSha,
+    ].join('\n');
+    const scope = `${xDate.slice(0, 8)}/${ARK_CONTROL_REGION}/${ARK_CONTROL_SERVICE}/request`;
+    const stringToSign = [
+        'HMAC-SHA256',
+        xDate,
+        scope,
+        createHash('sha256').update(canonical).digest('hex'),
+    ].join('\n');
+    // The derived signing key is a four-step HMAC chain: date, region, service, then
+    // the literal "request".
+    const kSigning = hmac(hmac(hmac(hmac(input.credentials.secretAccessKey, xDate.slice(0, 8)), ARK_CONTROL_REGION), ARK_CONTROL_SERVICE), 'request');
+    const signature = createHmac('sha256', kSigning).update(stringToSign).digest('hex');
+    return {
+        'content-type': contentType,
+        'host': ARK_CONTROL_HOST,
+        'x-content-sha256': contentSha,
+        'x-date': xDate,
+        'x-security-token': input.credentials.sessionToken,
+        'authorization': `HMAC-SHA256 Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+    };
+}
+/** Call one control-plane action. */
+export async function callArkControl(input) {
+    const query = `Action=${input.action}&Version=${ARK_CONTROL_VERSION}`;
+    const body = input.body ?? '';
+    const contentType = input.contentType;
+    const response = await input.fetchFn(`https://${ARK_CONTROL_HOST}/?${query}`, {
+        method: 'POST',
+        headers: {
+            ...attributedHeaders(signArkRequest({
+                method: 'POST',
+                query,
+                body,
+                credentials: input.credentials,
+                ...contentType === undefined ? {} : { contentType },
+            })),
+        },
+        body,
+        ...input.signal === undefined ? {} : { signal: input.signal },
+    });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok) {
+        throw new Error(`Ark control plane refused ${input.action} (HTTP ${response.status})`);
+    }
+    return payload;
+}
+/**
+ * Mint one ordinary API key for the account.
+ *
+ * The data plane refuses STS credentials (`403 Unsupported sts authentication
+ * method`) and takes only an API key, so this is the step that turns a sign-in into
+ * a usable credential. The shape is not guesswork — it was learned from the
+ * service's own validation, which reports each missing parameter in turn:
+ * `Name`, then `ProjectName`, then `ResourceInstances`, then
+ * `AccessControlInfo.AllowAll`. `ResourceInstances` must be a non-empty array (an
+ * empty one is rejected as invalid, while one empty object is accepted), and the
+ * body has to be JSON, because a nested structure is not expressible in the form
+ * encoding the flat actions use.
+ *
+ * The reply carries only an `Id`; the key itself comes from {@link readArkApiKey}.
+ *
+ * @param input - action inputs plus the credentials to sign with.
+ * @returns the new key's id.
+ * @throws {Error} when the control plane refuses.
+ */
+export async function createArkApiKey(input) {
+    const payload = await callArkControl({
+        action: 'CreateApiKey',
+        credentials: input.credentials,
+        fetchFn: input.fetchFn,
+        contentType: 'application/json',
+        body: JSON.stringify({
+            Name: input.name,
+            ProjectName: input.project ?? 'default',
+            ResourceInstances: [{}],
+            AccessControlInfo: { AllowAll: true },
+        }),
+        ...input.signal === undefined ? {} : { signal: input.signal },
+    });
+    const id = num(payload.Result?.Id);
+    if (id === undefined)
+        throw new Error('Ark CreateApiKey returned no key id');
+    return id;
+}
+/**
+ * Read one key's value.
+ *
+ * @param input - the key's id and the credentials to sign with.
+ * @returns the key, as the data plane expects it.
+ * @throws {Error} when the control plane refuses or states no key.
+ */
+export async function readArkApiKey(input) {
+    const payload = await callArkControl({
+        action: 'GetRawApiKey',
+        credentials: input.credentials,
+        fetchFn: input.fetchFn,
+        contentType: 'application/json',
+        body: JSON.stringify({ Id: input.id, ProjectName: input.project ?? 'default' }),
+        ...input.signal === undefined ? {} : { signal: input.signal },
+    });
+    const key = typeof payload.Result?.ApiKey === 'string' ? payload.Result.ApiKey.trim() : '';
+    if (key === '')
+        throw new Error('Ark GetRawApiKey returned no key');
+    return key;
+}
+/**
+ * Every key the account already has, newest first as the service lists them.
+ *
+ * @param input - the credentials to sign with.
+ * @returns the keys' ids and names.
+ */
+export async function listArkApiKeys(input) {
+    const payload = await callArkControl({
+        action: 'ListApiKeys',
+        credentials: input.credentials,
+        fetchFn: input.fetchFn,
+        contentType: 'application/json',
+        body: JSON.stringify({ PageSize: 50, ProjectName: input.project ?? 'default' }),
+        ...input.signal === undefined ? {} : { signal: input.signal },
+    });
+    const items = payload.Result?.Items;
+    if (!Array.isArray(items))
+        return [];
+    const out = [];
+    for (const raw of items) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const record = raw;
+        const id = num(record.Id);
+        if (id === undefined)
+            continue;
+        const name = typeof record.Name === 'string' && record.Name.trim() !== '' ? record.Name.trim() : undefined;
+        const status = typeof record.Status === 'string' && record.Status.trim() !== '' ? record.Status.trim() : undefined;
+        out.push({ id, ...name === undefined ? {} : { name }, ...status === undefined ? {} : { status } });
+    }
+    return out;
+}
+/** Read a finite number from a wire field. */
+function num(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+/**
+ * Read every model's free inference allowance.
+ *
+ * This is the allowance that exists without a subscription — the plan quota is a
+ * separate action that reports `Status: Reclaimed` for an account with no plan.
+ * Free usage is per model, and the free-usage field is omitted for models that have
+ * none, so those are skipped rather than reported as zero.
+ *
+ * @param payload - the decoded `ListModelChargeItems` body.
+ * @returns one entry per model that states a free allowance.
+ */
+export function parseArkFreeUsage(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return [];
+    const result = payload.Result;
+    if (typeof result !== 'object' || result === null)
+        return [];
+    const items = result.Items;
+    if (!Array.isArray(items))
+        return [];
+    const out = [];
+    for (const raw of items) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const item = raw;
+        const model = typeof item.FoundationModelName === 'string' ? item.FoundationModelName.trim() : '';
+        const usage = item.InferenceFreeUsage;
+        if (model === '' || typeof usage !== 'object' || usage === null)
+            continue;
+        const record = usage;
+        const total = num(record.Total);
+        const consumed = num(record.Consumed) ?? 0;
+        if (total === undefined || total <= 0)
+            continue;
+        out.push({ model, consumed, total });
+    }
+    return out;
+}
+/** A reset instant from an RFC 3339 string. */
+function instant(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'string' || value.trim() === '')
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * Read a plan's allowance out of a `GetCodingPlanUsage` / `GetAFPUsage` body.
+ *
+ * The service nests the metered periods under `coding_usage` (Coding Plan) or
+ * `afp_usage` (Agent Plan); each period is
+ * `{ label, used, total, percent, reset_at }`, which the CLI's own help documents
+ * with a worked example. An account with no plan answers `Status: Reclaimed` and no
+ * periods, which is a state to report rather than an error.
+ *
+ * @param payload - the decoded control-plane body.
+ * @returns the plan state and its periods.
+ */
+export function parseArkPlanUsage(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return { subscribed: false, periods: [] };
+    const result = payload.Result;
+    if (typeof result !== 'object' || result === null)
+        return { subscribed: false, periods: [] };
+    const record = result;
+    const status = typeof record.Status === 'string' && record.Status.trim() !== '' ? record.Status.trim() : undefined;
+    // The two editions name the same structure differently; either may be present.
+    const usage = [record.coding_usage, record.afp_usage, record.QuotaUsage]
+        .find((candidate) => typeof candidate === 'object' && candidate !== null);
+    const rawPeriods = usage?.periods ?? record.periods;
+    const periods = [];
+    if (Array.isArray(rawPeriods)) {
+        for (const raw of rawPeriods) {
+            if (typeof raw !== 'object' || raw === null)
+                continue;
+            const period = raw;
+            const label = typeof period.label === 'string' && period.label.trim() !== '' ? period.label.trim() : undefined;
+            if (label === undefined)
+                continue;
+            const resetsAt = instant(period.reset_at);
+            const used = num(period.used);
+            const total = num(period.total);
+            const percent = num(period.percent);
+            periods.push({
+                label,
+                ...used === undefined ? {} : { used },
+                ...total === undefined ? {} : { total },
+                ...percent === undefined ? {} : { percent },
+                ...resetsAt === undefined ? {} : { resetsAt },
+            });
+        }
+    }
+    const subscribed = typeof record.subscribed === 'boolean'
+        ? record.subscribed
+        : periods.length > 0 || (status !== undefined && status.toLowerCase() !== 'reclaimed');
+    return { subscribed, ...status === undefined ? {} : { status }, periods };
+}

package/lib/auth/ark-flow.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Volcengine Ark's `volc-sso` sign-in (China region).
+ *
+ * The contract here was read out of the official `@volcengine/ark-cli` 1.0.38
+ * binary — whose SHA-256 matches the manifest its npm package publishes — and then
+ * confirmed by a real sign-in that CLI performed, whose stored state and debug
+ * traffic are quoted below.
+ *
+ * The chain is three-legged, and only the first leg is OAuth:
+ *
+ * 1. **SSO** — `GET /authorize/oauth/authorize` with `response_type=code`, the
+ *    devtools client id, a loopback `redirect_uri`, `scope=Console:All:All`,
+ *    `state` and an S256 PKCE challenge; then `POST /authorize/oauth/token` with
+ *    `grant_type=authorization_code` and the verifier. The reply is
+ *    `{ id_token, refresh_token, client_id, timestamp_ms, expires_in: 900 }`,
+ *    which is exactly what the CLI stores in `identities/<id>/token.json`.
+ * 2. **STS** — the id token is exchanged for temporary `{ ak, sk, session_token,
+ *    expires_at }` credentials (`identities/<id>/sts.json`).
+ * 3. **A plan API key** — the signed control plane mints an "ordinary ARK API Key"
+ *    for that identity, and *that* key is what the data plane accepts.
+ *
+ * The data plane refuses the other two outright, which is how the plugin knows the
+ * key is the credential to keep: an id token bearer answers
+ * `403 Unsupported zti authentication method`, an AK/SK signature answers
+ * `403 Unsupported aksk authentication method`, while a UUID-shaped key is looked
+ * up (`401 The API key doesn't exist`).
+ *
+ * It is a public client: the exchange is `client_secret_post` with no secret, and
+ * the callback is a loopback listener, so the plugin's existing `LoopbackFlow`
+ * serves it unchanged.
+ *
+ * @module dsh-plugin-subscription-oauth/auth/ark-flow
+ */
+import type { PkcePair } from './pkce-flow.js';
+import type { ArkStsCredentials } from './ark-control.js';
+import type { FetchFn } from '../http.js';
+/** Identity host both the authorize and token endpoints live on. */
+export declare const ARK_SSO_ORIGIN = "https://signin.volcengine.com";
+/** Where the browser is sent to approve the sign-in. */
+export declare const ARK_AUTHORIZE_URL = "https://signin.volcengine.com/authorize/oauth/authorize";
+/** Where the authorization code is redeemed. */
+export declare const ARK_TOKEN_URL = "https://signin.volcengine.com/authorize/oauth/token";
+/**
+ * The CLI's devtools client for a sign-in on this machine.
+ *
+ * It is a public client identifier, not a secret: `client_secret_post` is used with
+ * no secret at all, which is what the binary shows for both devtools clients.
+ */
+export declare const ARK_CLIENT_ID = "trn:signin:::devtools/same-device";
+/** Client the CLI uses when the browser is on another device. */
+export declare const ARK_CROSS_DEVICE_CLIENT_ID = "trn:signin:::devtools/cross-device";
+/**
+ * Scope the console client asks for.
+ *
+ * Taken from a live sign-in the official CLI performed: the authorize URL it
+ * printed carried `scope=Console:All:All`, which this module originally omitted.
+ */
+export declare const ARK_SCOPE = "Console:All:All";
+/** Loopback path the identity service redirects to. */
+export declare const ARK_CALLBACK_PATH = "/oauth/callback";
+/**
+ * Ports tried in order for the callback listener.
+ *
+ * The CLI binds an ephemeral port and puts it in the redirect URI, so no port is
+ * privileged by the service; a short fixed list keeps the attempt predictable and
+ * stays out of the ranges the other routes already use (56121, 51121).
+ */
+export declare const ARK_CALLBACK_PORTS: readonly [51789, 51790, 51791, 51792];
+/** What one completed sign-in yields. */
+export interface ArkTokenSet {
+    /** Identity token the SSO issued. */
+    readonly idToken: string;
+    /**
+     * Temporary STS credentials, when the service returned them.
+     *
+     * The SSO endpoint's `access_token` is not an opaque bearer: it is a JSON document
+     * — `token_type: urn:ietf:params:oauth:token-type:access_token_sts` — carrying
+     * `access_key_id` / `secret_access_key` / `session_token`. Those sign the control
+     * plane, which is where the plan allowance lives, so this is the credential the
+     * quota reader needs. It is obtained from the same call as the id token; the
+     * account's broker is not involved.
+     */
+    readonly sts?: ArkStsCredentials;
+    /** Refresh token, when the service issued one. */
+    readonly refreshToken?: string;
+    /** Epoch milliseconds the id token stops being usable. */
+    readonly expiresAt: number;
+}
+/**
+ * Normalise the identity service's token response.
+ *
+ * @param payload - the decoded body.
+ * @param previousRefreshToken - the refresh token to keep when the reply omits one.
+ * @returns the token set.
+ * @throws {Error} when the reply carries no identity token.
+ */
+export declare function parseArkTokenPayload(payload: unknown, previousRefreshToken?: string): ArkTokenSet;
+/**
+ * Build the URL the browser is sent to.
+ *
+ * @param input - loopback redirect, state, and the PKCE pair.
+ * @returns the authorize URL.
+ */
+export declare function buildArkAuthorizeUrl(input: {
+    redirectUri: string;
+    state: string;
+    pkce: PkcePair;
+    clientId?: string;
+}): string;
+/**
+ * Redeem the authorization code.
+ *
+ * @param input - fetch, the code, and the PKCE pair it was issued against.
+ * @returns the token set.
+ * @throws {Error} when the service refuses or states no identity token.
+ */
+export declare function exchangeArkCode(input: {
+    fetchFn: FetchFn;
+    code: string;
+    redirectUri: string;
+    pkce: PkcePair;
+    signal: AbortSignal;
+}): Promise<ArkTokenSet>;
+/**
+ * Renew an identity token.
+ *
+ * @param input - fetch and the stored refresh token.
+ * @returns the renewed token set, keeping the refresh token when none is reissued.
+ * @throws {Error} when the service refuses.
+ */
+export declare function refreshArkToken(input: {
+    fetchFn: FetchFn;
+    refreshToken: string;
+}): Promise<ArkTokenSet>;

package/lib/auth/ark-flow.js

@@ -0,0 +1,239 @@
+/**
+ * Volcengine Ark's `volc-sso` sign-in (China region).
+ *
+ * The contract here was read out of the official `@volcengine/ark-cli` 1.0.38
+ * binary — whose SHA-256 matches the manifest its npm package publishes — and then
+ * confirmed by a real sign-in that CLI performed, whose stored state and debug
+ * traffic are quoted below.
+ *
+ * The chain is three-legged, and only the first leg is OAuth:
+ *
+ * 1. **SSO** — `GET /authorize/oauth/authorize` with `response_type=code`, the
+ *    devtools client id, a loopback `redirect_uri`, `scope=Console:All:All`,
+ *    `state` and an S256 PKCE challenge; then `POST /authorize/oauth/token` with
+ *    `grant_type=authorization_code` and the verifier. The reply is
+ *    `{ id_token, refresh_token, client_id, timestamp_ms, expires_in: 900 }`,
+ *    which is exactly what the CLI stores in `identities/<id>/token.json`.
+ * 2. **STS** — the id token is exchanged for temporary `{ ak, sk, session_token,
+ *    expires_at }` credentials (`identities/<id>/sts.json`).
+ * 3. **A plan API key** — the signed control plane mints an "ordinary ARK API Key"
+ *    for that identity, and *that* key is what the data plane accepts.
+ *
+ * The data plane refuses the other two outright, which is how the plugin knows the
+ * key is the credential to keep: an id token bearer answers
+ * `403 Unsupported zti authentication method`, an AK/SK signature answers
+ * `403 Unsupported aksk authentication method`, while a UUID-shaped key is looked
+ * up (`401 The API key doesn't exist`).
+ *
+ * It is a public client: the exchange is `client_secret_post` with no secret, and
+ * the callback is a loopback listener, so the plugin's existing `LoopbackFlow`
+ * serves it unchanged.
+ *
+ * @module dsh-plugin-subscription-oauth/auth/ark-flow
+ */
+import { attributedHeaders } from './headers.js';
+/** Identity host both the authorize and token endpoints live on. */
+export const ARK_SSO_ORIGIN = 'https://signin.volcengine.com';
+/** Where the browser is sent to approve the sign-in. */
+export const ARK_AUTHORIZE_URL = `${ARK_SSO_ORIGIN}/authorize/oauth/authorize`;
+/** Where the authorization code is redeemed. */
+export const ARK_TOKEN_URL = `${ARK_SSO_ORIGIN}/authorize/oauth/token`;
+/**
+ * The CLI's devtools client for a sign-in on this machine.
+ *
+ * It is a public client identifier, not a secret: `client_secret_post` is used with
+ * no secret at all, which is what the binary shows for both devtools clients.
+ */
+export const ARK_CLIENT_ID = 'trn:signin:::devtools/same-device';
+/** Client the CLI uses when the browser is on another device. */
+export const ARK_CROSS_DEVICE_CLIENT_ID = 'trn:signin:::devtools/cross-device';
+/**
+ * Scope the console client asks for.
+ *
+ * Taken from a live sign-in the official CLI performed: the authorize URL it
+ * printed carried `scope=Console:All:All`, which this module originally omitted.
+ */
+export const ARK_SCOPE = 'Console:All:All';
+/** Loopback path the identity service redirects to. */
+export const ARK_CALLBACK_PATH = '/oauth/callback';
+/**
+ * Ports tried in order for the callback listener.
+ *
+ * The CLI binds an ephemeral port and puts it in the redirect URI, so no port is
+ * privileged by the service; a short fixed list keeps the attempt predictable and
+ * stays out of the ranges the other routes already use (56121, 51121).
+ */
+export const ARK_CALLBACK_PORTS = [51789, 51790, 51791, 51792];
+/** Read a non-empty trimmed string. */
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/** Read a finite number. */
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** Decode one JWT's payload without verifying it, for the expiry claim. */
+function jwtExpiry(token) {
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1] ?? '', 'base64url').toString('utf8'));
+        if (typeof payload !== 'object' || payload === null)
+            return undefined;
+        const exp = finite(payload.exp);
+        return exp === undefined ? undefined : exp * 1000;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** How long a token set is assumed to live when nothing states it. */
+const ASSUMED_ID_TOKEN_TTL_MS = 60 * 60 * 1000;
+/**
+ * Read the STS credentials the SSO endpoint hands back.
+ *
+ * The `access_token` is a JSON document rather than an opaque string, and its
+ * `token_type` says what it is. A service that answers with an ordinary opaque
+ * access token yields nothing here, which is not an error: the id token still works
+ * for the sign-in, only the quota becomes unreadable.
+ *
+ * @param payload - the decoded token response.
+ * @returns the credentials, or undefined when the reply carried none.
+ */
+function stsFrom(payload) {
+    const accessToken = text(payload.access_token);
+    if (accessToken === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(accessToken);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    const accessKeyId = text(record.access_key_id);
+    const secretAccessKey = text(record.secret_access_key);
+    const sessionToken = text(record.session_token);
+    if (accessKeyId === undefined || secretAccessKey === undefined || sessionToken === undefined) {
+        return undefined;
+    }
+    const stated = finite(payload.expires_in);
+    return {
+        accessKeyId,
+        secretAccessKey,
+        sessionToken,
+        expiresAt: Date.now() + (stated === undefined ? 900 : stated) * 1000,
+    };
+}
+/**
+ * Normalise the identity service's token response.
+ *
+ * @param payload - the decoded body.
+ * @param previousRefreshToken - the refresh token to keep when the reply omits one.
+ * @returns the token set.
+ * @throws {Error} when the reply carries no identity token.
+ */
+export function parseArkTokenPayload(payload, previousRefreshToken) {
+    if (typeof payload !== 'object' || payload === null) {
+        throw new Error('Ark sign-in returned no token payload');
+    }
+    const record = payload;
+    const idToken = text(record.id_token) ?? text(record.access_token);
+    if (idToken === undefined)
+        throw new Error('Ark sign-in returned an empty id_token');
+    const refreshToken = text(record.refresh_token) ?? previousRefreshToken;
+    const sts = stsFrom(record);
+    const stated = finite(record.id_token_expires_at);
+    const expiresAt = stated === undefined
+        // The JWT states its own expiry; a reply that omits both is assumed short-lived
+        // rather than trusted forever.
+        ? jwtExpiry(idToken) ?? Date.now() + ASSUMED_ID_TOKEN_TTL_MS
+        : stated < 1e12 ? stated * 1000 : stated;
+    return {
+        idToken,
+        ...sts === undefined ? {} : { sts },
+        ...refreshToken === undefined ? {} : { refreshToken },
+        expiresAt,
+    };
+}
+/** Describe a refusal from the identity service. */
+async function failure(response, what) {
+    const payload = await response.json().catch(() => undefined);
+    const record = typeof payload === 'object' && payload !== null ? payload : {};
+    const described = text(record.error_description) ?? text(record.error) ?? text(record.message);
+    return new Error(`${what} failed (HTTP ${response.status})${described === undefined ? '' : `: ${described}`}`);
+}
+/**
+ * Build the URL the browser is sent to.
+ *
+ * @param input - loopback redirect, state, and the PKCE pair.
+ * @returns the authorize URL.
+ */
+export function buildArkAuthorizeUrl(input) {
+    const url = new URL(ARK_AUTHORIZE_URL);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', input.clientId ?? ARK_CLIENT_ID);
+    url.searchParams.set('redirect_uri', input.redirectUri);
+    url.searchParams.set('scope', ARK_SCOPE);
+    url.searchParams.set('state', input.state);
+    url.searchParams.set('code_challenge', input.pkce.challenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    return url.toString();
+}
+/**
+ * Redeem the authorization code.
+ *
+ * @param input - fetch, the code, and the PKCE pair it was issued against.
+ * @returns the token set.
+ * @throws {Error} when the service refuses or states no identity token.
+ */
+export async function exchangeArkCode(input) {
+    const response = await input.fetchFn(ARK_TOKEN_URL, {
+        method: 'POST',
+        headers: {
+            ...attributedHeaders(),
+            'content-type': 'application/x-www-form-urlencoded',
+            accept: 'application/json',
+        },
+        body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            client_id: ARK_CLIENT_ID,
+            code: input.code,
+            redirect_uri: input.redirectUri,
+            code_verifier: input.pkce.verifier,
+        }).toString(),
+        signal: input.signal,
+    });
+    if (!response.ok)
+        throw await failure(response, 'Ark token exchange');
+    return parseArkTokenPayload(await response.json());
+}
+/**
+ * Renew an identity token.
+ *
+ * @param input - fetch and the stored refresh token.
+ * @returns the renewed token set, keeping the refresh token when none is reissued.
+ * @throws {Error} when the service refuses.
+ */
+export async function refreshArkToken(input) {
+    const response = await input.fetchFn(ARK_TOKEN_URL, {
+        method: 'POST',
+        headers: {
+            ...attributedHeaders(),
+            'content-type': 'application/x-www-form-urlencoded',
+            accept: 'application/json',
+        },
+        body: new URLSearchParams({
+            grant_type: 'refresh_token',
+            client_id: ARK_CLIENT_ID,
+            refresh_token: input.refreshToken,
+        }).toString(),
+    });
+    if (!response.ok)
+        throw await failure(response, 'Ark token refresh');
+    return parseArkTokenPayload(await response.json(), input.refreshToken);
+}