@circle-rd/auth-ai 0.0.0-stage → 0.1.0

package/dist/server/backchannel-logout.d.ts

@@ -0,0 +1,47 @@
+import type { AuthClient } from "../client.js";
+/**
+ * Remembers the `jti` of accepted logout tokens until they expire. Share it
+ * across replicas (e.g. a Redis `SET NX PX`): a per-process store only stops
+ * replays that hit the same instance.
+ */
+export interface ReplayStore {
+    /** Returns true the first time a `jti` is claimed, false on a replay. */
+    claim(jti: string, expiresAt: number): Promise<boolean>;
+}
+export declare class MemoryReplayStore implements ReplayStore {
+    #private;
+    claim(jti: string, expiresAt: number): Promise<boolean>;
+}
+export interface LogoutTokenClaims {
+    readonly sid: string;
+    readonly sub: string;
+    readonly jti: string;
+    readonly iat: number;
+    readonly exp: number;
+}
+type LogoutAuth = Pick<AuthClient, "verifyJwt" | "config">;
+/**
+ * Validates an OIDC Back-Channel Logout token (spec §2.6) and records its
+ * `jti`. auth-service always names both the session and the user.
+ */
+export declare function verifyLogoutToken(auth: LogoutAuth, token: string, replayStore: ReplayStore): Promise<LogoutTokenClaims>;
+export interface BackchannelLogoutEvent {
+    /** End every local session whose stored `sid` equals this one. */
+    readonly sid: string;
+    /** For per-user state, when you keep any. */
+    readonly sub: string;
+}
+export interface BackchannelLogoutHandlerOptions {
+    readonly auth: LogoutAuth;
+    readonly onLogout: (event: BackchannelLogoutEvent) => Promise<void> | void;
+    readonly replayStore?: ReplayStore;
+    /** Receives every rejected token and failed callback: the response carries no detail. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Web-standard handler for the application's back-channel logout endpoint.
+ * It is called without cookies or credentials: mount it outside any session
+ * or CSRF protection.
+ */
+export declare function createBackchannelLogoutHandler(options: BackchannelLogoutHandlerOptions): (request: Request) => Promise<Response>;
+export {};

package/dist/server/backchannel-logout.js

@@ -0,0 +1,105 @@
+import { ERR } from "../errors.js";
+const LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+const LOGOUT_TOKEN_TYP = "logout+jwt";
+// auth-service issues 120 s tokens; anything far beyond is not one of its.
+const MAX_LOGOUT_TOKEN_LIFETIME_SECONDS = 600;
+const MAX_BODY_BYTES = 16_384;
+export class MemoryReplayStore {
+    #seen = new Map();
+    claim(jti, expiresAt) {
+        const now = Date.now() / 1000;
+        for (const [seenJti, seenExpiry] of this.#seen) {
+            if (seenExpiry <= now)
+                this.#seen.delete(seenJti);
+        }
+        if (this.#seen.has(jti))
+            return Promise.resolve(false);
+        this.#seen.set(jti, expiresAt);
+        return Promise.resolve(true);
+    }
+}
+/**
+ * Validates an OIDC Back-Channel Logout token (spec §2.6) and records its
+ * `jti`. auth-service always names both the session and the user.
+ */
+export async function verifyLogoutToken(auth, token, replayStore) {
+    const payload = await auth.verifyJwt(token, {
+        audience: auth.config.clientId,
+        typ: LOGOUT_TOKEN_TYP,
+    });
+    const { events, nonce, jti, sid, sub, iat, exp } = payload;
+    const hasEvent = typeof events === "object" && events !== null && LOGOUT_EVENT in events;
+    if (!hasEvent) {
+        throw ERR.TOK_001("The logout token lacks the back-channel logout event");
+    }
+    if (nonce !== undefined) {
+        throw ERR.TOK_001("A logout token must not carry a nonce");
+    }
+    if (typeof jti !== "string" || !jti || typeof sid !== "string" || !sid) {
+        throw ERR.TOK_001("The logout token lacks jti or sid");
+    }
+    if (typeof sub !== "string" || typeof iat !== "number" || exp === undefined) {
+        throw ERR.TOK_001("The logout token lacks sub, iat or exp");
+    }
+    const now = Date.now() / 1000;
+    if (iat > now + auth.config.clockToleranceSeconds ||
+        exp - iat > MAX_LOGOUT_TOKEN_LIFETIME_SECONDS) {
+        throw ERR.TOK_001("The logout token has an implausible lifetime");
+    }
+    if (!(await replayStore.claim(jti, exp))) {
+        throw ERR.TOK_001("The logout token was already used");
+    }
+    return { sid, sub, jti, iat, exp };
+}
+const NO_STORE = { "cache-control": "no-store" };
+function jsonError(status, error) {
+    return new Response(JSON.stringify({ error }), {
+        status,
+        headers: { ...NO_STORE, "content-type": "application/json" },
+    });
+}
+/**
+ * Web-standard handler for the application's back-channel logout endpoint.
+ * It is called without cookies or credentials: mount it outside any session
+ * or CSRF protection.
+ */
+export function createBackchannelLogoutHandler(options) {
+    const replayStore = options.replayStore ?? new MemoryReplayStore();
+    return async (request) => {
+        if (request.method !== "POST") {
+            return new Response(null, {
+                status: 405,
+                headers: { ...NO_STORE, allow: "POST" },
+            });
+        }
+        const declaredLength = Number(request.headers.get("content-length") ?? 0);
+        const isForm = (request.headers.get("content-type") ?? "")
+            .toLowerCase()
+            .startsWith("application/x-www-form-urlencoded");
+        if (!isForm || declaredLength > MAX_BODY_BYTES) {
+            return jsonError(400, "invalid_request");
+        }
+        const body = await request.text();
+        const token = body.length <= MAX_BODY_BYTES
+            ? new URLSearchParams(body).get("logout_token")
+            : null;
+        if (!token)
+            return jsonError(400, "invalid_request");
+        let claims;
+        try {
+            claims = await verifyLogoutToken(options.auth, token, replayStore);
+        }
+        catch (err) {
+            options.onError?.(err);
+            return jsonError(400, "invalid_request");
+        }
+        try {
+            await options.onLogout({ sid: claims.sid, sub: claims.sub });
+        }
+        catch (err) {
+            options.onError?.(err);
+            return jsonError(500, "server_error");
+        }
+        return new Response(null, { status: 204, headers: NO_STORE });
+    };
+}

package/dist/server/bearer.d.ts

@@ -0,0 +1,30 @@
+import type { AccessTokenClaims } from "../claims.js";
+import type { AuthClient } from "../client.js";
+/** Extracts the token of an `Authorization: Bearer <token>` header. */
+export declare function extractBearerToken(authorization: string | null | undefined): string;
+export interface VerifiedAccessToken {
+    /** The end user, or `null` for a `client_credentials` token (machine call). */
+    readonly userId: string | null;
+    /** The OAuth client (application slug) the token was issued to. */
+    readonly clientId: string;
+    readonly scopes: readonly string[];
+    readonly audiences: readonly string[];
+    readonly claims: AccessTokenClaims;
+}
+export interface BearerVerifierOptions {
+    /** The audience this API accepts: its RFC 8707 resource identifier. */
+    readonly audience: string;
+}
+export interface BearerVerifier {
+    /** Verifies a raw JWT access token. */
+    verify(token: string): Promise<VerifiedAccessToken>;
+    /** Verifies the token of an `Authorization` header. */
+    verifyHeader(authorization: string | null | undefined): Promise<VerifiedAccessToken>;
+}
+/**
+ * Verifies JWT access tokens minted for this API (`aud` contains `audience`).
+ * Opaque tokens are refused: they carry no audience this API could trust.
+ */
+export declare function createBearerVerifier(auth: Pick<AuthClient, "verifyJwt">, options: BearerVerifierOptions): BearerVerifier;
+/** Throws TOK_004 unless the token carries every listed scope. */
+export declare function requireScopes(token: Pick<VerifiedAccessToken, "scopes">, ...required: string[]): void;

package/dist/server/bearer.js

@@ -0,0 +1,58 @@
+import { accessTokenClaimsSchema } from "../claims.js";
+import { ERR } from "../errors.js";
+import { z } from "zod";
+const BEARER_PATTERN = /^Bearer +([A-Za-z0-9\-._~+/]+=*)$/i;
+/** Extracts the token of an `Authorization: Bearer <token>` header. */
+export function extractBearerToken(authorization) {
+    const match = authorization ? BEARER_PATTERN.exec(authorization) : null;
+    const token = match?.[1];
+    if (!token)
+        throw ERR.TOK_003();
+    return token;
+}
+const audienceSchema = z.url();
+/**
+ * Verifies JWT access tokens minted for this API (`aud` contains `audience`).
+ * Opaque tokens are refused: they carry no audience this API could trust.
+ */
+export function createBearerVerifier(auth, options) {
+    const parsedAudience = audienceSchema.safeParse(options.audience);
+    if (!parsedAudience.success) {
+        throw ERR.CFG_001("audience must be the URL of this API");
+    }
+    const audience = parsedAudience.data;
+    async function verify(token) {
+        if (token.split(".").length !== 3) {
+            throw ERR.TOK_001("Only JWT access tokens are accepted");
+        }
+        const payload = await auth.verifyJwt(token, { audience });
+        const claims = accessTokenClaimsSchema.safeParse(payload);
+        if (!claims.success) {
+            throw ERR.TOK_001("The access token is not bound to a client", {
+                cause: claims.error,
+            });
+        }
+        const { sub, azp, aud, scope } = claims.data;
+        return {
+            // For client_credentials tokens `sub` is the client id itself.
+            userId: sub === azp ? null : sub,
+            clientId: azp,
+            scopes: scope ? scope.split(" ") : [],
+            audiences: typeof aud === "string" ? [aud] : aud,
+            claims: claims.data,
+        };
+    }
+    return {
+        verify,
+        verifyHeader: async (authorization) => verify(extractBearerToken(authorization)),
+    };
+}
+/** Throws TOK_004 unless the token carries every listed scope. */
+export function requireScopes(token, ...required) {
+    const missing = required.filter((scope) => !token.scopes.includes(scope));
+    if (missing.length > 0) {
+        throw ERR.TOK_004(`Missing required scope: ${missing.join(" ")}`, {
+            details: { missing: missing.join(" ") },
+        });
+    }
+}

package/dist/server/billing.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import type { JsonHttp } from "../http.js";
+export declare const subscriptionViewSchema: z.ZodObject<{
+    plan: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    isActive: z.ZodBoolean;
+    expiresAt: z.ZodNullable<z.ZodString>;
+    stripeStatus: z.ZodNullable<z.ZodString>;
+    currentPeriodStart: z.ZodNullable<z.ZodString>;
+    currentPeriodEnd: z.ZodNullable<z.ZodString>;
+    cancelAtPeriodEnd: z.ZodBoolean;
+    canceledAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const usageViewSchema: z.ZodObject<{
+    periodStart: z.ZodString;
+    features: z.ZodArray<z.ZodObject<{
+        featureKey: z.ZodString;
+        unit: z.ZodNullable<z.ZodString>;
+        usageLimit: z.ZodNumber;
+        used: z.ZodNumber;
+        remaining: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const invoiceViewSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodString;
+    billingReason: z.ZodNullable<z.ZodString>;
+    currency: z.ZodString;
+    amountDue: z.ZodNumber;
+    amountPaid: z.ZodNumber;
+    amountRemaining: z.ZodNumber;
+    periodStart: z.ZodNullable<z.ZodString>;
+    periodEnd: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    hostedInvoiceUrl: z.ZodNullable<z.ZodString>;
+    invoicePdf: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const invoicePageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodString;
+        billingReason: z.ZodNullable<z.ZodString>;
+        currency: z.ZodString;
+        amountDue: z.ZodNumber;
+        amountPaid: z.ZodNumber;
+        amountRemaining: z.ZodNumber;
+        periodStart: z.ZodNullable<z.ZodString>;
+        periodEnd: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        hostedInvoiceUrl: z.ZodNullable<z.ZodString>;
+        invoicePdf: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SubscriptionView = z.infer<typeof subscriptionViewSchema>;
+export type UsageView = z.infer<typeof usageViewSchema>;
+export type InvoiceView = z.infer<typeof invoiceViewSchema>;
+export type InvoicePage = z.infer<typeof invoicePageSchema>;
+export interface ListInvoicesOptions {
+    /** 1 to 100. */
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+/**
+ * What a user holds and has consumed in this application. The application is
+ * the one behind the machine token: it cannot read another one.
+ */
+export declare class BillingApi {
+    #private;
+    constructor(http: JsonHttp);
+    /** `null` when the user holds no subscription. */
+    getSubscription(userId: string): Promise<SubscriptionView | null>;
+    getUsage(userId: string): Promise<UsageView>;
+    /** Newest first, keyset-paginated: pass `nextCursor` back until it is null. */
+    listInvoices(userId: string, options?: ListInvoicesOptions): Promise<InvoicePage>;
+}

package/dist/server/billing.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+const SCOPE = "billing:read";
+export const subscriptionViewSchema = z.object({
+    plan: z.object({ id: z.string(), name: z.string() }),
+    isActive: z.boolean(),
+    expiresAt: z.string().nullable(),
+    stripeStatus: z.string().nullable(),
+    currentPeriodStart: z.string().nullable(),
+    currentPeriodEnd: z.string().nullable(),
+    cancelAtPeriodEnd: z.boolean(),
+    canceledAt: z.string().nullable(),
+});
+export const usageViewSchema = z.object({
+    periodStart: z.string(),
+    features: z.array(z.object({
+        featureKey: z.string(),
+        unit: z.string().nullable(),
+        /** The plan's hard cap for the period; -1 means unlimited. */
+        usageLimit: z.number(),
+        used: z.number(),
+        /** Units left before the cap; null when unlimited. */
+        remaining: z.number().nullable(),
+    })),
+});
+export const invoiceViewSchema = z.object({
+    id: z.string(),
+    status: z.string(),
+    billingReason: z.string().nullable(),
+    currency: z.string(),
+    amountDue: z.number(),
+    amountPaid: z.number(),
+    amountRemaining: z.number(),
+    periodStart: z.string().nullable(),
+    periodEnd: z.string().nullable(),
+    createdAt: z.string(),
+    hostedInvoiceUrl: z.string().nullable(),
+    invoicePdf: z.string().nullable(),
+});
+export const invoicePageSchema = z.object({
+    items: z.array(invoiceViewSchema),
+    nextCursor: z.string().nullable(),
+});
+const subscriptionResponseSchema = z.object({
+    subscription: subscriptionViewSchema.nullable(),
+});
+/**
+ * What a user holds and has consumed in this application. The application is
+ * the one behind the machine token: it cannot read another one.
+ */
+export class BillingApi {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    /** `null` when the user holds no subscription. */
+    async getSubscription(userId) {
+        const { subscription } = await this.#http.request({
+            method: "GET",
+            path: `/api/app/billing/users/${encodeURIComponent(userId)}/subscription`,
+            scope: SCOPE,
+            schema: subscriptionResponseSchema,
+        });
+        return subscription;
+    }
+    getUsage(userId) {
+        return this.#http.request({
+            method: "GET",
+            path: `/api/app/billing/users/${encodeURIComponent(userId)}/usage`,
+            scope: SCOPE,
+            schema: usageViewSchema,
+        });
+    }
+    /** Newest first, keyset-paginated: pass `nextCursor` back until it is null. */
+    listInvoices(userId, options = {}) {
+        return this.#http.request({
+            method: "GET",
+            path: `/api/app/billing/users/${encodeURIComponent(userId)}/invoices`,
+            scope: SCOPE,
+            query: { limit: options.limit, cursor: options.cursor },
+            schema: invoicePageSchema,
+        });
+    }
+}

package/dist/server/consumption.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { JsonHttp } from "../http.js";
+declare const storedAggregateSchema: z.ZodObject<{
+    key: z.ZodString;
+    total: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export interface ConsumptionReport {
+    readonly userId: string;
+    /** Alphanumeric and dots, 64 characters at most. */
+    readonly key: string;
+    /** May be negative to credit back. */
+    readonly value: number;
+    /** The same key reported twice counts once: set it to make retries safe. */
+    readonly idempotencyKey?: string;
+}
+export interface ConsumptionResult {
+    /** `total` is a decimal string: the running total is not bounded by a double. */
+    readonly aggregate: {
+        readonly key: string;
+        readonly total: string;
+    };
+    /** True when the key prices a metered feature and was billed through Stripe. */
+    readonly metered: boolean;
+}
+export type ConsumptionAggregate = z.infer<typeof storedAggregateSchema>;
+/**
+ * Usage the application reports for its users, for features billed on
+ * consumption. The application is the one behind the machine token.
+ */
+export declare class ConsumptionApi {
+    #private;
+    constructor(http: JsonHttp);
+    report(input: ConsumptionReport): Promise<ConsumptionResult>;
+    /** Every running total of a user. */
+    list(userId: string): Promise<ConsumptionAggregate[]>;
+    /** One running total; rejects (API_001, CONS_003) when the key was never reported. */
+    get(userId: string, key: string): Promise<ConsumptionAggregate>;
+}
+export {};

package/dist/server/consumption.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { ERR } from "../errors.js";
+const reportSchema = z.object({
+    userId: z.string().min(1),
+    key: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-zA-Z0-9.]+$/, "key must be alphanumeric with dots"),
+    value: z.number().finite(),
+    idempotencyKey: z.string().trim().min(1).max(200).optional(),
+});
+const WRITE_SCOPE = "consumption:write";
+const READ_SCOPE = "consumption:read";
+const aggregateSchema = z.object({ key: z.string(), total: z.string() });
+const storedAggregateSchema = aggregateSchema.extend({
+    updatedAt: z.string(),
+});
+const reportResponseSchema = z.object({
+    success: z.literal(true),
+    metered: z.boolean().optional(),
+    aggregate: aggregateSchema,
+});
+/**
+ * Usage the application reports for its users, for features billed on
+ * consumption. The application is the one behind the machine token.
+ */
+export class ConsumptionApi {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    async report(input) {
+        const body = reportSchema.safeParse(input);
+        if (!body.success) {
+            throw ERR.CFG_001(`Invalid consumption report: ${body.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`, { cause: body.error });
+        }
+        const response = await this.#http.request({
+            method: "POST",
+            path: this.#path(body.data.userId),
+            scope: WRITE_SCOPE,
+            body: {
+                key: body.data.key,
+                value: body.data.value,
+                ...(body.data.idempotencyKey === undefined
+                    ? {}
+                    : { idempotencyKey: body.data.idempotencyKey }),
+            },
+            schema: reportResponseSchema,
+        });
+        return {
+            aggregate: response.aggregate,
+            metered: response.metered ?? false,
+        };
+    }
+    /** Every running total of a user. */
+    async list(userId) {
+        const { aggregates } = await this.#http.request({
+            method: "GET",
+            path: this.#path(userId),
+            scope: READ_SCOPE,
+            schema: z.object({ aggregates: z.array(storedAggregateSchema) }),
+        });
+        return aggregates;
+    }
+    /** One running total; rejects (API_001, CONS_003) when the key was never reported. */
+    async get(userId, key) {
+        const { aggregate } = await this.#http.request({
+            method: "GET",
+            path: `${this.#path(userId)}/${encodeURIComponent(key)}`,
+            scope: READ_SCOPE,
+            schema: z.object({ aggregate: storedAggregateSchema }),
+        });
+        return aggregate;
+    }
+    #path(userId) {
+        return `/api/app/consumption/users/${encodeURIComponent(userId)}`;
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,11 @@
+export { createBearerVerifier, extractBearerToken, requireScopes, } from "./bearer.js";
+export type { BearerVerifier, BearerVerifierOptions, VerifiedAccessToken, } from "./bearer.js";
+export { MemoryReplayStore, createBackchannelLogoutHandler, verifyLogoutToken, } from "./backchannel-logout.js";
+export type { BackchannelLogoutEvent, BackchannelLogoutHandlerOptions, LogoutTokenClaims, ReplayStore, } from "./backchannel-logout.js";
+export { MachineApi, createMachineApi } from "./machine-api.js";
+export { BillingApi } from "./billing.js";
+export type { InvoicePage, InvoiceView, ListInvoicesOptions, SubscriptionView, UsageView, } from "./billing.js";
+export { ConsumptionApi } from "./consumption.js";
+export type { ConsumptionAggregate, ConsumptionReport, ConsumptionResult, } from "./consumption.js";
+export { bearerChallenge, protectedResourceMetadata, protectedResourceMetadataPath, } from "./protected-resource.js";
+export type { BearerChallengeOptions, ProtectedResourceMetadata, ProtectedResourceMetadataOptions, } from "./protected-resource.js";

package/dist/server/index.js

@@ -0,0 +1,6 @@
+export { createBearerVerifier, extractBearerToken, requireScopes, } from "./bearer.js";
+export { MemoryReplayStore, createBackchannelLogoutHandler, verifyLogoutToken, } from "./backchannel-logout.js";
+export { MachineApi, createMachineApi } from "./machine-api.js";
+export { BillingApi } from "./billing.js";
+export { ConsumptionApi } from "./consumption.js";
+export { bearerChallenge, protectedResourceMetadata, protectedResourceMetadataPath, } from "./protected-resource.js";

package/dist/server/machine-api.d.ts

@@ -0,0 +1,17 @@
+import type { AuthClient } from "../client.js";
+import { BillingApi } from "./billing.js";
+import { ConsumptionApi } from "./consumption.js";
+type MachineAuth = Pick<AuthClient, "clientCredentials" | "config" | "fetch">;
+/**
+ * The auth-service REST API as the application's backend: every call carries a
+ * `client_credentials` token minted from the application's own secret. The
+ * scopes `billing:read`, `consumption:read` and `consumption:write` must be
+ * granted to the application by a superadmin.
+ */
+export declare class MachineApi {
+    readonly billing: BillingApi;
+    readonly consumption: ConsumptionApi;
+    constructor(auth: MachineAuth);
+}
+export declare function createMachineApi(auth: MachineAuth): MachineApi;
+export {};

package/dist/server/machine-api.js

@@ -0,0 +1,31 @@
+import { ERR } from "../errors.js";
+import { BillingApi } from "./billing.js";
+import { ConsumptionApi } from "./consumption.js";
+import { JsonHttp } from "../http.js";
+import { MachineTokenProvider } from "./machine-tokens.js";
+/**
+ * The auth-service REST API as the application's backend: every call carries a
+ * `client_credentials` token minted from the application's own secret. The
+ * scopes `billing:read`, `consumption:read` and `consumption:write` must be
+ * granted to the application by a superadmin.
+ */
+export class MachineApi {
+    billing;
+    consumption;
+    constructor(auth) {
+        if (!auth.config.clientSecret) {
+            throw ERR.CFG_001("The machine API requires a confidential client");
+        }
+        const http = new JsonHttp({
+            baseUrl: auth.config.issuer,
+            fetch: auth.fetch,
+            timeoutMs: auth.config.timeoutMs,
+            tokens: new MachineTokenProvider(auth),
+        });
+        this.billing = new BillingApi(http);
+        this.consumption = new ConsumptionApi(http);
+    }
+}
+export function createMachineApi(auth) {
+    return new MachineApi(auth);
+}

package/dist/server/machine-tokens.d.ts

@@ -0,0 +1,13 @@
+import type { AuthClient } from "../client.js";
+/**
+ * `client_credentials` tokens of the application, one per scope set. They are
+ * cached until shortly before they expire, and concurrent callers share one
+ * request to the token endpoint.
+ */
+export declare class MachineTokenProvider {
+    #private;
+    constructor(auth: Pick<AuthClient, "clientCredentials">);
+    getToken(scope: string): Promise<string>;
+    /** Drops a token the API refused, e.g. after a secret rotation. */
+    invalidate(scope: string): void;
+}

package/dist/server/machine-tokens.js

@@ -0,0 +1,49 @@
+import { AuthAiError, ERR } from "../errors.js";
+// A cached token is renewed this long before it expires.
+const EXPIRY_SKEW_SECONDS = 30;
+/**
+ * `client_credentials` tokens of the application, one per scope set. They are
+ * cached until shortly before they expire, and concurrent callers share one
+ * request to the token endpoint.
+ */
+export class MachineTokenProvider {
+    #auth;
+    #cache = new Map();
+    #inflight = new Map();
+    constructor(auth) {
+        this.#auth = auth;
+    }
+    getToken(scope) {
+        const cached = this.#cache.get(scope);
+        if (cached && cached.expiresAt - EXPIRY_SKEW_SECONDS > Date.now() / 1000) {
+            return Promise.resolve(cached.accessToken);
+        }
+        const pending = this.#inflight.get(scope);
+        if (pending)
+            return pending;
+        const request = this.#auth
+            .clientCredentials({ scope })
+            .catch((err) => {
+            // The scope goes in `details` (for logs); the message stays generic.
+            if (err instanceof AuthAiError &&
+                err.details?.["oauthError"] === "invalid_scope") {
+                throw ERR.TOK_004(undefined, { details: { scope }, cause: err });
+            }
+            throw err;
+        })
+            .then((tokens) => {
+            this.#cache.set(scope, {
+                accessToken: tokens.accessToken,
+                expiresAt: tokens.expiresAt,
+            });
+            return tokens.accessToken;
+        })
+            .finally(() => this.#inflight.delete(scope));
+        this.#inflight.set(scope, request);
+        return request;
+    }
+    /** Drops a token the API refused, e.g. after a secret rotation. */
+    invalidate(scope) {
+        this.#cache.delete(scope);
+    }
+}