@xenosystem/agent-cli 0.5.107 → 0.5.109

package/node_modules/@xeno-corporation/account/dist/index.d.ts

@@ -0,0 +1,883 @@
+import { z } from 'zod';
+import { a as DpopSigner, T as TokenStore } from './tokenStore-CnIo2ILq.js';
+export { D as DpopProofArgs, K as Keychain, k as keychainStore, m as memoryStore, n as normalizeDpopHtu } from './tokenStore-CnIo2ILq.js';
+
+/**
+ * The XENO Account & Ledger contract — canonical types.
+ *
+ * These Zod schemas ARE the contract every branch (app) and the origin
+ * (xeno-platform) speak. See `XENO ACCOUNT - ARCHITECTURE.md`. Money is always
+ * integer **micro-credits** (1 credit = 1_000_000 µcr) — never a float.
+ */
+/** 1 credit expressed in the integer base unit. */
+declare const MICRO_PER_CREDIT = 1000000;
+/** A surface = the originating app/branch, the "from where" attribution. */
+declare const surfaceSchema: z.ZodString;
+type Surface = z.infer<typeof surfaceSchema>;
+/**
+ * The canonical XENO account as a branch sees it. `id` is the canonical
+ * `platform_user_id`; identity is keyed on (provider, subject) upstream, never
+ * on the email — `email` here is contact/display only.
+ */
+declare const accountSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodString;
+    username: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    displayName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    emailVerified: z.ZodDefault<z.ZodBoolean>;
+    /** Linked app surfaces for this account (unified-account view). */
+    linkedSurfaces: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    email: string;
+    username: string | null;
+    displayName: string | null;
+    avatarUrl: string | null;
+    emailVerified: boolean;
+    linkedSurfaces: string[];
+}, {
+    id: string;
+    email: string;
+    username?: string | null | undefined;
+    displayName?: string | null | undefined;
+    avatarUrl?: string | null | undefined;
+    emailVerified?: boolean | undefined;
+    linkedSurfaces?: string[] | undefined;
+}>;
+type Account = z.infer<typeof accountSchema>;
+declare const tokenSetSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    /** Opaque or JWT; the SDK treats it as opaque. */
+    tokenType: z.ZodDefault<z.ZodString>;
+    expiresAt: z.ZodDefault<z.ZodNullable<z.ZodDate>>;
+    refreshToken: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** OIDC ID token (authentication only — never sent to resource APIs). */
+    idToken: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    scope: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Session id claim, the join key for back-channel logout. */
+    sid: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Signature-verified claims; never populated by unverified decoding. */
+    accessClaims: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    idClaims: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, "strip", z.ZodTypeAny, {
+    accessToken: string;
+    tokenType: string;
+    expiresAt: Date | null;
+    refreshToken: string | null;
+    idToken: string | null;
+    scope: string[];
+    sid: string | null;
+    accessClaims: Record<string, unknown> | null;
+    idClaims: Record<string, unknown> | null;
+}, {
+    accessToken: string;
+    tokenType?: string | undefined;
+    expiresAt?: Date | null | undefined;
+    refreshToken?: string | null | undefined;
+    idToken?: string | null | undefined;
+    scope?: string[] | undefined;
+    sid?: string | null | undefined;
+    accessClaims?: Record<string, unknown> | null | undefined;
+    idClaims?: Record<string, unknown> | null | undefined;
+}>;
+type TokenSet = z.infer<typeof tokenSetSchema>;
+/** Raw OAuth 2.0 token endpoint response (snake_case, as servers emit it). */
+declare const oauthTokenResponseSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodDefault<z.ZodString>;
+    expires_in: z.ZodOptional<z.ZodNumber>;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    id_token: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    access_token: string;
+    token_type: string;
+    scope?: string | undefined;
+    expires_in?: number | undefined;
+    refresh_token?: string | undefined;
+    id_token?: string | undefined;
+}, {
+    access_token: string;
+    scope?: string | undefined;
+    token_type?: string | undefined;
+    expires_in?: number | undefined;
+    refresh_token?: string | undefined;
+    id_token?: string | undefined;
+}>;
+type OAuthTokenResponse = z.infer<typeof oauthTokenResponseSchema>;
+/**
+ * The three balances every double-entry wallet exposes. Gate spend decisions
+ * on `availableMicro` (most conservative). All values are integer micro-credits.
+ */
+declare const balanceSchema: z.ZodObject<{
+    /** Settled balance. */
+    postedMicro: z.ZodNumber;
+    /** Settled minus active holds. */
+    pendingMicro: z.ZodNumber;
+    /** Most conservative spendable amount — gate approvals on this. */
+    availableMicro: z.ZodNumber;
+    currency: z.ZodDefault<z.ZodLiteral<"credits">>;
+    asOf: z.ZodDefault<z.ZodDate>;
+}, "strip", z.ZodTypeAny, {
+    postedMicro: number;
+    pendingMicro: number;
+    availableMicro: number;
+    currency: "credits";
+    asOf: Date;
+}, {
+    postedMicro: number;
+    pendingMicro: number;
+    availableMicro: number;
+    currency?: "credits" | undefined;
+    asOf?: Date | undefined;
+}>;
+type Balance = z.infer<typeof balanceSchema>;
+declare const meterAggregationSchema: z.ZodEnum<["sum", "count", "max", "min", "unique_count", "latest"]>;
+type MeterAggregation = z.infer<typeof meterAggregationSchema>;
+/**
+ * A usage event posted to the meter. `transactionId` MUST be deterministic
+ * (a hash of the business event), never a random id minted at send time — it
+ * is the dedup key (32–34 day window) that makes metering exactly-once.
+ */
+declare const usageEventSchema: z.ZodObject<{
+    surface: z.ZodString;
+    /** Stable, producer-supplied dedup id. */
+    transactionId: z.ZodString;
+    operation: z.ZodString;
+    model: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    provider: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Pre-computed cost in micro-credits, if the caller priced it. */
+    costMicro: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    inputTokens: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    outputTokens: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    /** Arbitrary attribution dimensions (project, workspace, …). */
+    dimensions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    occurredAt: z.ZodOptional<z.ZodDate>;
+}, "strip", z.ZodTypeAny, {
+    surface: string;
+    transactionId: string;
+    operation: string;
+    model: string | null;
+    provider: string | null;
+    costMicro: number | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    dimensions: Record<string, string>;
+    occurredAt?: Date | undefined;
+}, {
+    surface: string;
+    transactionId: string;
+    operation: string;
+    model?: string | null | undefined;
+    provider?: string | null | undefined;
+    costMicro?: number | null | undefined;
+    inputTokens?: number | null | undefined;
+    outputTokens?: number | null | undefined;
+    dimensions?: Record<string, string> | undefined;
+    occurredAt?: Date | undefined;
+}>;
+type UsageEvent = z.infer<typeof usageEventSchema>;
+declare const usageResultSchema: z.ZodObject<{
+    accepted: z.ZodBoolean;
+    /** True when the event was a duplicate (idempotent no-op). */
+    duplicate: z.ZodDefault<z.ZodBoolean>;
+    costMicro: z.ZodNumber;
+    transactionId: z.ZodString;
+    balance: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        /** Settled balance. */
+        postedMicro: z.ZodNumber;
+        /** Settled minus active holds. */
+        pendingMicro: z.ZodNumber;
+        /** Most conservative spendable amount — gate approvals on this. */
+        availableMicro: z.ZodNumber;
+        currency: z.ZodDefault<z.ZodLiteral<"credits">>;
+        asOf: z.ZodDefault<z.ZodDate>;
+    }, "strip", z.ZodTypeAny, {
+        postedMicro: number;
+        pendingMicro: number;
+        availableMicro: number;
+        currency: "credits";
+        asOf: Date;
+    }, {
+        postedMicro: number;
+        pendingMicro: number;
+        availableMicro: number;
+        currency?: "credits" | undefined;
+        asOf?: Date | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    transactionId: string;
+    costMicro: number;
+    accepted: boolean;
+    duplicate: boolean;
+    balance: {
+        postedMicro: number;
+        pendingMicro: number;
+        availableMicro: number;
+        currency: "credits";
+        asOf: Date;
+    } | null;
+}, {
+    transactionId: string;
+    costMicro: number;
+    accepted: boolean;
+    duplicate?: boolean | undefined;
+    balance?: {
+        postedMicro: number;
+        pendingMicro: number;
+        availableMicro: number;
+        currency?: "credits" | undefined;
+        asOf?: Date | undefined;
+    } | null | undefined;
+}>;
+type UsageResult = z.infer<typeof usageResultSchema>;
+/** A two-phase hold (reserve → settle/void) for hard per-use gating. */
+declare const holdRequestSchema: z.ZodObject<{
+    surface: z.ZodString;
+    /** Idempotency key for the hold itself. */
+    holdId: z.ZodString;
+    amountMicro: z.ZodNumber;
+    operation: z.ZodString;
+    expiresInSeconds: z.ZodDefault<z.ZodNumber>;
+    dimensions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    surface: string;
+    operation: string;
+    dimensions: Record<string, string>;
+    holdId: string;
+    amountMicro: number;
+    expiresInSeconds: number;
+}, {
+    surface: string;
+    operation: string;
+    holdId: string;
+    amountMicro: number;
+    dimensions?: Record<string, string> | undefined;
+    expiresInSeconds?: number | undefined;
+}>;
+type HoldRequest = z.infer<typeof holdRequestSchema>;
+declare const holdSchema: z.ZodObject<{
+    holdId: z.ZodString;
+    state: z.ZodEnum<["held", "settled", "voided", "expired"]>;
+    amountMicro: z.ZodNumber;
+    settledMicro: z.ZodDefault<z.ZodNumber>;
+    balance: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        /** Settled balance. */
+        postedMicro: z.ZodNumber;
+        /** Settled minus active holds. */
+        pendingMicro: z.ZodNumber;
+        /** Most conservative spendable amount — gate approvals on this. */
+        availableMicro: z.ZodNumber;
+        currency: z.ZodDefault<z.ZodLiteral<"credits">>;
+        asOf: z.ZodDefault<z.ZodDate>;
+    }, "strip", z.ZodTypeAny, {
+        postedMicro: number;
+        pendingMicro: number;
+        availableMicro: number;
+        currency: "credits";
+        asOf: Date;
+    }, {
+        postedMicro: number;
+        pendingMicro: number;
+        availableMicro: number;
+        currency?: "credits" | undefined;
+        asOf?: Date | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    balance: {
+        postedMicro: number;
+        pendingMicro: number;
+        availableMicro: number;
+        currency: "credits";
+        asOf: Date;
+    } | null;
+    holdId: string;
+    amountMicro: number;
+    state: "held" | "settled" | "voided" | "expired";
+    settledMicro: number;
+}, {
+    holdId: string;
+    amountMicro: number;
+    state: "held" | "settled" | "voided" | "expired";
+    balance?: {
+        postedMicro: number;
+        pendingMicro: number;
+        availableMicro: number;
+        currency?: "credits" | undefined;
+        asOf?: Date | undefined;
+    } | null | undefined;
+    settledMicro?: number | undefined;
+}>;
+type Hold = z.infer<typeof holdSchema>;
+declare const authzCheckSchema: z.ZodObject<{
+    /** e.g. `user:abc` or `agent:scout`. */
+    subject: z.ZodString;
+    relation: z.ZodString;
+    /** e.g. `workspace:acme` or `post:123`. */
+    object: z.ZodString;
+    context: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    object: string;
+    subject: string;
+    relation: string;
+    context: Record<string, unknown>;
+}, {
+    object: string;
+    subject: string;
+    relation: string;
+    context?: Record<string, unknown> | undefined;
+}>;
+type AuthzCheck = z.infer<typeof authzCheckSchema>;
+declare const authzResultSchema: z.ZodObject<{
+    allowed: z.ZodBoolean;
+    /** Optional reason/trace for debugging (never authoritative). */
+    reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    allowed: boolean;
+    reason: string | null;
+}, {
+    allowed: boolean;
+    reason?: string | null | undefined;
+}>;
+type AuthzResult = z.infer<typeof authzResultSchema>;
+/** Convert whole credits → integer micro-credits. */
+declare function toMicro(credits: number): number;
+/** Convert integer micro-credits → whole credits (may be fractional). */
+declare function fromMicro(micro: number): number;
+
+/**
+ * Normalised error taxonomy for the account client. Every failure a branch can
+ * see maps to one of these codes so callers branch on `code`, never on strings.
+ */
+type AccountErrorCode = 'DISABLED' | 'UNREACHABLE' | 'INVALID_TOKEN' | 'INSUFFICIENT_CREDITS' | 'CONFLICT' | 'INVALID_RESPONSE' | 'BAD_REQUEST' | 'NOT_FOUND' | 'RATE_LIMITED' | 'PLATFORM_ERROR';
+declare class AccountError extends Error {
+    readonly code: AccountErrorCode;
+    readonly httpStatus: number | null;
+    readonly retryable: boolean;
+    readonly retryAfterMs: number | null;
+    readonly oauthError: string | null;
+    constructor(args: {
+        code: AccountErrorCode;
+        message: string;
+        httpStatus?: number | null;
+        retryable?: boolean;
+        retryAfterMs?: number | null;
+        oauthError?: string | null;
+    });
+}
+/** Map an HTTP status to the right error code. */
+declare function codeForStatus(status: number): AccountErrorCode;
+
+/**
+ * Minimal, dependency-free HTTP transport for the account client.
+ *
+ * Design rules (from `XENO ACCOUNT - ARCHITECTURE.md` §4.4):
+ *  - Mutations carry an `Idempotency-Key`; the SDK NEVER auto-retries a mutation
+ *    without one (would risk a double-charge). With a key, retrying is safe
+ *    because the origin replays the first response.
+ *  - GETs are safely retried on network/5xx with capped backoff.
+ *  - The bearer token is sent in the Authorization header, never logged.
+ */
+interface TransportOptions {
+    /** Injectable for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    /** Retry attempts for idempotent requests (GET, or mutation with a key). */
+    maxRetries?: number;
+    userAgent?: string;
+    /** Maximum decoded response bytes. Oversized responses fail, never truncate. */
+    maxResponseBytes?: number;
+}
+interface RequestArgs {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    url: string;
+    token?: string | null;
+    tokenType?: 'Bearer' | 'DPoP';
+    body?: unknown;
+    /** Required to make a mutation retry-safe. */
+    idempotencyKey?: string;
+    /** Extra headers (e.g. DPoP proof). */
+    headers?: Record<string, string>;
+    /** Host-owned authorization refreshed for each attempt; DPoP proofs are single use. */
+    authorization?: RequestAuthorizationProvider;
+    /** Only canonical OAuth grant endpoints opt into safe error-code extraction. */
+    oauthErrorResponse?: boolean;
+    /** Caller cancellation is nonretryable and covers authorization/body as well as fetch. */
+    signal?: AbortSignal;
+}
+interface RequestAuthorization {
+    token: string;
+    tokenType: 'Bearer' | 'DPoP';
+    headers?: Record<string, string>;
+}
+type RequestAuthorizationProvider = (method: RequestArgs['method'], url: string) => Promise<RequestAuthorization>;
+type AuthorizationInput = string | RequestAuthorization | RequestAuthorizationProvider;
+declare class Transport {
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly userAgent;
+    private readonly maxResponseBytes;
+    constructor(opts?: TransportOptions);
+    /** Perform a request and return parsed JSON (or null for empty bodies). */
+    request<T = unknown>(args: RequestArgs): Promise<T>;
+    private once;
+}
+
+/**
+ * Account client — the identity-read side. Resolves a token to its canonical
+ * XENO account.
+ *
+ * Targets the v2 `/api/v2/me`, with a graceful fall-back to the legacy
+ * `/api/auth/me` envelope (`{ success, user: {...} }`) so it works against the
+ * live platform today, before the v2 surface ships.
+ */
+declare class AccountClient {
+    private readonly base;
+    private readonly transport;
+    constructor(base: string, transport: Transport);
+    /** Resolve a token to its account, or throw an AccountError. */
+    me(auth: AuthorizationInput): Promise<Account>;
+}
+/**
+ * Normalise either a v2 account or the legacy `{ user }` envelope into the
+ * canonical {@link Account}. Tolerant of snake/camel; null only if no id+email.
+ */
+declare function normalize(body: unknown): Account | null;
+
+/** Caller-facing input types (defaults not yet applied). */
+type UsageEventInput = z.input<typeof usageEventSchema>;
+type HoldRequestInput = z.input<typeof holdRequestSchema>;
+/**
+ * Ledger client — the spend side of the contract. Targets the origin's
+ * `/api/v2/ledger/*` surface. Every mutation is idempotent: usage events key on
+ * a deterministic `transactionId`, holds on a `holdId`, and both are sent as the
+ * `Idempotency-Key` so a retry can never double-charge.
+ *
+ * Spend decisions gate on `balance.availableMicro` (the most conservative of the
+ * three balances). All amounts are integer micro-credits.
+ */
+declare class LedgerClient {
+    private readonly apiBase;
+    private readonly transport;
+    constructor(apiBase: string, transport: Transport);
+    /** Posted / pending / available balance for the token's account. */
+    getBalance(auth: AuthorizationInput): Promise<Balance>;
+    /**
+     * Record a usage event (the meter). Idempotent on `transactionId`; a duplicate
+     * returns `{ duplicate: true }` and does not charge again.
+     */
+    recordUsage(auth: AuthorizationInput, event: UsageEventInput): Promise<UsageResult>;
+    /**
+     * Reserve credits for a per-use action (phase 1 of two-phase spend). Rejected
+     * with `INSUFFICIENT_CREDITS` if `available < amount`. Idempotent on `holdId`.
+     */
+    hold(auth: AuthorizationInput, req: HoldRequestInput): Promise<Hold>;
+    /**
+     * Settle a hold for the actual cost (phase 2). Posting less than the held
+     * amount auto-restores the remainder. Idempotent on `holdId`.
+     */
+    settle(auth: AuthorizationInput, holdId: string, actualCostMicro: number): Promise<Hold>;
+    /** Release a hold without charging (failure/cancel). Idempotent on `holdId`. */
+    void(auth: AuthorizationInput, holdId: string): Promise<Hold>;
+}
+
+/**
+ * Authorization client — ReBAC checks against the origin's central authz
+ * service (OpenFGA-backed). A branch asks "may this subject perform this
+ * relation on this object?"; the origin is the single source of truth so
+ * cross-app permission inheritance works without per-app role sync.
+ *
+ * Fail-closed: any transport error surfaces as an AccountError; callers must
+ * treat a non-`allowed` result (or an error) as deny.
+ */
+declare class AuthzClient {
+    private readonly apiBase;
+    private readonly transport;
+    constructor(apiBase: string, transport: Transport);
+    check(auth: AuthorizationInput, check: AuthzCheck): Promise<AuthzResult>;
+}
+
+/**
+ * OIDC relying-party flows (OAuth 2.1 / RFC 9700 compliant):
+ *  - Authorization Code + PKCE (S256) for web + native (RFC 8252).
+ *  - Device Authorization Grant (RFC 8628) for CLI / headless.
+ *
+ * No implicit flow, no ROPC — both are forbidden. PKCE is always used, even for
+ * confidential clients.
+ */
+interface OidcConfig {
+    /** Issuer base, e.g. https://xenostudio.ai (endpoints derived or overridden). */
+    issuer: string;
+    clientId: string;
+    /** Confidential clients only; public clients (SPA/CLI/native) omit it. */
+    clientSecret?: string;
+    redirectUri?: string;
+    scopes?: string[];
+    authorizeUrl?: string;
+    tokenUrl?: string;
+    deviceAuthorizationUrl?: string;
+    jwksUrl?: string;
+    /** Required for every public-client token. The private key remains host-owned. */
+    dpopSigner: DpopSigner;
+}
+interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+/**
+ * RFC 7636 PKCE pair (S256). Browser-safe: uses Web Crypto (`globalThis.crypto`),
+ * available in Node 20+ AND every browser — no `node:crypto`, so this build
+ * imports cleanly in a web SPA and an Electron renderer (XENO AUTH §11, §14.3).
+ * Async because Web Crypto's SHA-256 (`subtle.digest`) is async.
+ */
+declare function generatePkce(): Promise<PkcePair>;
+declare function generateState(): string;
+/**
+ * Build the authorize URL for the Authorization Code + PKCE flow. The caller
+ * persists `{ state, verifier }` (e.g. encrypted in a cookie/flow token) and
+ * passes the verifier back to {@link exchangeCode}.
+ */
+declare function buildAuthorizeUrl(cfg: OidcConfig, args: {
+    state: string;
+    codeChallenge: string;
+    redirectUri?: string;
+    scopes?: string[];
+    nonce?: string;
+    prompt?: 'login';
+    maxAge?: number;
+    acrValues?: 'urn:xeno:acr:fresh';
+}): string;
+/** Exchange an authorization code for tokens (carries the PKCE verifier). */
+declare function exchangeCode(cfg: OidcConfig, transport: Transport, args: {
+    code: string;
+    codeVerifier: string;
+    redirectUri?: string;
+    expectedNonce: string;
+    expectedScopes?: string[];
+    signal?: AbortSignal;
+}): Promise<TokenSet>;
+/**
+ * Refresh tokens. The origin rotates the refresh token on every use
+ * (RFC 9700 §2.2.2) — always persist the returned `refreshToken`, and treat a
+ * confirmed invalid_grant as re-auth required. A lost reply is uncertain and
+ * must not be replayed blindly; the owning client/store retains that state.
+ */
+declare function refreshTokens(cfg: OidcConfig, transport: Transport, refreshToken: string): Promise<TokenSet>;
+interface DeviceAuthorization {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string | null;
+    expiresAt: Date;
+    intervalSeconds: number;
+}
+declare function startDeviceAuthorization(cfg: OidcConfig, transport: Transport, scopes?: string[]): Promise<DeviceAuthorization>;
+/**
+ * Poll the token endpoint for a device grant, honouring `authorization_pending`
+ * / `slow_down` per RFC 8628. Resolves when the user approves, rejects on
+ * expiry/denial. `onPending` lets a CLI print progress.
+ */
+declare function pollDeviceToken(cfg: OidcConfig, transport: Transport, device: DeviceAuthorization, opts?: {
+    sleep?: (ms: number) => Promise<void>;
+    signal?: AbortSignal;
+}): Promise<TokenSet>;
+
+interface BrokerTokenRequest {
+    clientId: string;
+    scopes: string[];
+    resource: 'https://api.xenostudio.ai';
+    childDpopJkt: string;
+}
+/** Transport is supplied by Hub/Electron main after OS peer verification. */
+interface BrokerAdapter {
+    getToken(request: BrokerTokenRequest): Promise<TokenSet | null>;
+    logout?(): Promise<void>;
+}
+
+interface VerifiedAccessClaims {
+    iss: string;
+    sub: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    sid: string;
+    client_id: string;
+    azp: string;
+    scope: string;
+    typ: 'at+jwt';
+    auth_epoch: number;
+    auth_time?: number;
+    acr?: string;
+    amr?: string[];
+    cnf: {
+        jkt: string;
+    };
+    act?: {
+        client_id: 'xeno-hub';
+        installation_id_hash: string;
+        sub?: string;
+    };
+}
+interface VerifiedIdClaims {
+    iss: string;
+    sub: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    sid: string;
+    auth_time: number;
+    nonce?: string;
+    email?: string;
+    email_verified?: boolean;
+    preferred_username?: string;
+    name?: string;
+    picture?: string;
+}
+interface VerifiedLogoutClaims {
+    iss: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    jti: string;
+    sid?: string;
+    sub?: string;
+    events: {
+        'http://schemas.openid.net/event/backchannel-logout': Record<string, never>;
+    };
+}
+declare function verifyAccessToken(args: {
+    token: string;
+    transport: Transport;
+    issuer: string;
+    clientId: string;
+    dpopJkt: string;
+    jwksUrl?: string;
+    expectedScopes?: string[];
+    requireBrokerActor?: boolean;
+}): Promise<VerifiedAccessClaims>;
+declare function verifyIdToken(args: {
+    token: string;
+    transport: Transport;
+    issuer: string;
+    clientId: string;
+    jwksUrl?: string;
+    expectedNonce?: string;
+    expectedSubject?: string;
+}): Promise<VerifiedIdClaims>;
+/** Verify an OpenID Connect Back-Channel Logout Token before local revocation. */
+declare function verifyLogoutToken(args: {
+    token: string;
+    transport: Transport;
+    issuer: string;
+    clientId: string;
+    jwksUrl?: string;
+}): Promise<VerifiedLogoutClaims>;
+
+/**
+ * Configuration for a branch (app) wiring into the XENO account origin.
+ *
+ *   issuer  — the origin's auth base (e.g. https://xenostudio.ai)
+ *   apiBase — the origin's private API base for ledger/authz
+ *             (e.g. https://api.xenostudio.ai)
+ *   surface — this app's attribution tag, e.g. 'xeno_post'
+ */
+interface XenoAccountClientConfig {
+    issuer: string;
+    apiBase: string;
+    surface: Surface;
+    oidc: Omit<OidcConfig, 'issuer'>;
+    transport?: TransportOptions;
+    /** Where the rotating refresh token lives (default: memory). Desktop/CLI pass
+     *  a keychainStore; web passes a cookie/memory store (XENO AUTH §11). */
+    store?: TokenStore;
+    /** Explicit credential override — chain step 2 (XENO_API_KEY / provisioned key /
+     *  remote-run token). Bypasses interactive paths. Defaults to env XENO_API_KEY. */
+    apiKey?: string;
+    /** Optional Hub broker. Failure falls through to this app's own refresh. */
+    broker?: BrokerAdapter;
+}
+/**
+ * The one client every XENO branch uses. Composes identity (OIDC + /me),
+ * ledger (idempotent metering + two-phase holds) and authz (ReBAC) behind a
+ * single, framework-agnostic facade.
+ *
+ * Standalone-first: a branch only constructs this in cloud mode (when a
+ * platform URL is configured). With it absent, the app runs on its own auth.
+ */
+declare class XenoAccountClient {
+    readonly surface: Surface;
+    readonly account: AccountClient;
+    readonly ledger: LedgerClient;
+    readonly authz: AuthzClient;
+    private readonly oidcConfig;
+    private readonly transport;
+    private readonly store;
+    private readonly apiKey?;
+    private readonly broker?;
+    private readonly refreshStoreKey;
+    private readonly refreshPendingKey;
+    private access;
+    private user;
+    private interactive?;
+    private resolutionFlight;
+    private generation;
+    private locallySignedOut;
+    private readonly listeners;
+    constructor(cfg: XenoAccountClientConfig);
+    /**
+     * Return a valid Bearer for the gate, walking the chain:
+     *   1 in-memory access token → 2 explicit override (apiKey/XENO_API_KEY) →
+     *   3 [broker — host-wired] → 4 this product's own refresh token →
+     *   5 interactive sign-in (host-provided; skipped when `silent`) → null.
+     */
+    getAccessToken(opts?: {
+        scopes?: string[];
+        silent?: boolean;
+    }): Promise<string | null>;
+    private resolveSession;
+    /** Register the host's interactive sign-in (loopback PKCE / device grant). */
+    setInteractiveSignIn(fn: (scopes?: string[]) => Promise<TokenSet>): void;
+    isAuthenticated(): boolean;
+    currentUser(): Account | null;
+    /** Subscribe to login/refresh/logout/backchannel. Returns an unsubscribe fn. */
+    onAuthChanged(cb: (a: Account | null) => void): () => void;
+    /** Local wipe only, used after durable host-side invalidation/reconciliation. */
+    signOutLocal(): Promise<void>;
+    /** Revoke this subject-owned session, then always clear local state. */
+    signOut(): Promise<{
+        serverRevoked: boolean;
+    }>;
+    /** Step-up protected, subject-keyed global logout. Only authorized clients can call it. */
+    signOutEverywhere(): Promise<void>;
+    private setUnauthenticated;
+    private emit;
+    private storeRead;
+    private cacheCurrent;
+    private exclusiveStore;
+    private reserveSignIn;
+    private resolveInteractive;
+    /** Cache the access token, persist the rotated refresh token, update the user. */
+    private applyTokenSet;
+    private cancelCommittedSignIn;
+    /**
+     * Begin "Continue with XENO". Returns the authorize URL to redirect to, plus
+     * the `{ state, verifier }` the caller MUST persist (encrypted) to complete
+     * the flow in {@link completeSignIn}.
+     */
+    beginSignIn(args?: {
+        redirectUri?: string;
+        scopes?: string[];
+        fresh?: boolean;
+    }): Promise<{
+        url: string;
+        state: string;
+        nonce: string;
+        pkce: PkcePair;
+    }>;
+    /** Complete the code flow: exchange `code` (with the saved verifier) for tokens,
+     *  then cache the access token + persist the refresh token + set the user. */
+    completeSignIn(args: {
+        code: string;
+        codeVerifier: string;
+        expectedNonce: string;
+        expectedScopes?: string[];
+        redirectUri?: string;
+        signal?: AbortSignal;
+    }): Promise<TokenSet>;
+    private bindSignInCancellation;
+    /** Headers for one sender-constrained resource request. */
+    authorization(method: string, url: string, opts?: {
+        scopes?: string[];
+        silent?: boolean;
+    }): Promise<RequestAuthorization | null>;
+    /** Verify and sender-constrain a previously persisted access token. Server
+     * consumers use this for encrypted per-workspace sessions without placing
+     * those tokens into the process-global client cache. */
+    authorizationForToken(token: string, method: string, url: string, expectedScopes?: string[]): Promise<RequestAuthorization>;
+    /** Verify a provider-originated Back-Channel Logout Token. */
+    verifyBackchannelLogout(token: string): Promise<VerifiedLogoutClaims>;
+    private createProof;
+    /** Rotate tokens. Persist the returned refreshToken; a failure means re-auth. */
+    refresh(refreshToken: string): Promise<TokenSet>;
+    startDeviceLogin(scopes?: string[]): Promise<DeviceAuthorization>;
+    awaitDeviceLogin(device: Awaited<ReturnType<XenoAccountClient['startDeviceLogin']>>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<TokenSet>;
+}
+
+interface BffSessionState {
+    authenticated: boolean;
+    user?: {
+        id: string;
+        email?: string;
+        displayName?: string | null;
+    };
+    expiresAt?: string;
+}
+/** Browser facade for the server-held web session. It never receives tokens. */
+declare class BffSessionClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly csrf;
+    constructor(baseUrl: string | undefined, fetchImpl: typeof fetch | undefined, csrf: () => string | null);
+    loginUrl(returnUrl: string): string;
+    session(): Promise<BffSessionState>;
+    refresh(idempotencyKey: string): Promise<BffSessionState>;
+    logout(): Promise<void>;
+    private request;
+}
+
+/**
+ * redaction — the runtime guard that a token-shaped string never lands in a log
+ * (XENO AUTH §12; complements the connector-kit CI lint that fails on
+ * `accessToken`/`refreshToken` in a log call). Use `redact(x)` before logging
+ * anything that might carry a JWT / opaque token.
+ */
+/** Mask any token-shaped substrings, keeping a short prefix for correlation. */
+declare function redact(input: unknown): string;
+
+interface DpopReplayStore {
+    /** Atomic insert-if-absent, retained through expiresAtMs. Unavailable is an error, not true. */
+    consume(input: {
+        keyThumbprint: string;
+        proofId: string;
+        method: string;
+        url: string;
+        expiresAtMs: number;
+    }): Promise<boolean>;
+}
+interface ResourceAuthorizationOptions {
+    issuer: string;
+    clientIds: readonly string[];
+    transport: Transport;
+    replayStore: DpopReplayStore;
+    /** Trusted origin revocation/epoch read. No token or private proof is passed to logs. */
+    sessionActive(claims: Readonly<VerifiedAccessClaims>, token: string): Promise<boolean>;
+}
+interface ResourceRequest {
+    method: string;
+    url: string;
+    authorization: string;
+    proof: string;
+    scopes?: readonly string[];
+    nonce?: string;
+}
+interface ResourceAuthorizationReceipt {
+    readonly claims: Readonly<VerifiedAccessClaims>;
+    /** Rechecks original identity without consuming the same proof again. */
+    revalidate(): Promise<void>;
+}
+/** Canonical resource-server verification. Identity is not a product capability grant. */
+declare function createResourceRequestAuthorizer(options: ResourceAuthorizationOptions): {
+    authorize(request: ResourceRequest): Promise<ResourceAuthorizationReceipt>;
+};
+/** Current origin introspection, not a decoded-JWT or positive-cache substitute. */
+declare function createOidcIntrospectionSessionAuthority(options: {
+    issuer: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): (claims: Readonly<VerifiedAccessClaims>, token: string) => Promise<boolean>;
+
+export { type Account, AccountClient, AccountError, type AccountErrorCode, type AuthorizationInput, type AuthzCheck, AuthzClient, type AuthzResult, type Balance, BffSessionClient, type BffSessionState, type BrokerAdapter, type BrokerTokenRequest, type DeviceAuthorization, type DpopReplayStore, DpopSigner, type Hold, type HoldRequest, type HoldRequestInput, LedgerClient, MICRO_PER_CREDIT, type MeterAggregation, type OAuthTokenResponse, type OidcConfig, type PkcePair, type RequestArgs, type RequestAuthorization, type RequestAuthorizationProvider, type ResourceAuthorizationOptions, type ResourceAuthorizationReceipt, type ResourceRequest, type Surface, type TokenSet, TokenStore, Transport, type TransportOptions, type UsageEvent, type UsageEventInput, type UsageResult, type VerifiedAccessClaims, type VerifiedIdClaims, type VerifiedLogoutClaims, XenoAccountClient, type XenoAccountClientConfig, accountSchema, authzCheckSchema, authzResultSchema, balanceSchema, buildAuthorizeUrl, codeForStatus, createOidcIntrospectionSessionAuthority, createResourceRequestAuthorizer, exchangeCode, fromMicro, generatePkce, generateState, holdRequestSchema, holdSchema, meterAggregationSchema, normalize, oauthTokenResponseSchema, pollDeviceToken, redact, refreshTokens, startDeviceAuthorization, surfaceSchema, toMicro, tokenSetSchema, usageEventSchema, usageResultSchema, verifyAccessToken, verifyIdToken, verifyLogoutToken };