/* tslint:disable */
/* eslint-disable */

/*
 * Hand-written — NOT regenerated by `napi build`.
 *
 * `napi build --dts native.d.ts` writes the raw generated bindings to
 * `native.d.ts`. Those bindings *throw* on failure; this file presents the
 * public contract instead: every fallible operation returns a
 * `@byteslice/result` `Result<T, AuthFailure>` (`{ data }` on success,
 * `{ failure }` on error), assembled by `index.js` from the structured error
 * the Rust layer emits. Consumers write `if (result.failure) …` and never
 * `try/catch` for domain errors.
 *
 * The plain success types (`TokenResult`, `AuthResult`, `AutoStrategyOptions`)
 * are re-used from `native.d.ts`; the strategy classes/functions are
 * re-declared here with `Result`-returning signatures. `AuthFailure` mirrors
 * `AuthError` in `packages/stack-auth/src/error.rs`; the `stack-auth-node`
 * drift test `ts_auth_failure_union_matches_error_codes` guards it.
 */

import type { Result } from "@byteslice/result";
import type { TokenResult, AuthResult, AutoStrategyOptions } from "./native";

export type { TokenResult, AuthResult, AutoStrategyOptions };

/** Fields present on every `AuthFailure`. */
interface FailureBase {
  /** The live `Error` thrown across the FFI boundary, with `.message`/`.code`. */
  error: Error;
  /** Actionable diagnostic guidance, when the error carries it. */
  help?: string;
  /** A URL with more detail, when the error carries it. */
  url?: string;
}

/**
 * A domain failure returned in the `failure` arm of a `Result`. Discriminated
 * by `type`; narrow on it to access per-variant payload (e.g.
 * `WORKSPACE_MISMATCH`'s `expected`/`actual`).
 */
export type AuthFailure =
  | (FailureBase & { type: "REQUEST_ERROR" })
  | (FailureBase & { type: "ACCESS_DENIED" })
  | (FailureBase & { type: "EXPIRED_TOKEN" })
  | (FailureBase & { type: "INVALID_GRANT" })
  | (FailureBase & { type: "INVALID_CLIENT" })
  | (FailureBase & { type: "INVALID_URL" })
  | (FailureBase & { type: "INVALID_REGION" })
  | (FailureBase & { type: "INVALID_TOKEN" })
  | (FailureBase & { type: "SERVER_ERROR" })
  | (FailureBase & { type: "NOT_AUTHENTICATED" })
  | (FailureBase & { type: "MISSING_WORKSPACE_CRN" })
  | (FailureBase & { type: "INVALID_ACCESS_KEY" })
  | (FailureBase & { type: "INVALID_CRN" })
  | (FailureBase & { type: "WORKSPACE_MISMATCH"; expected: string; actual: string })
  | (FailureBase & { type: "INVALID_WORKSPACE_ID" })
  | (FailureBase & { type: "ALREADY_CONSUMED" })
  | (FailureBase & { type: "INTERNAL_ERROR" })
  | (FailureBase & { type: "CUSTOM" })
  | (FailureBase & { type: "STORE_ERROR" });

/** The machine-readable discriminant carried by every {@link AuthFailure}. */
export type AuthErrorCode = AuthFailure["type"];

/**
 * An auth strategy that auto-detects credentials from environment variables
 * and the local profile store.
 */
export declare class AutoStrategy {
  /** Detect available credentials and return an `AutoStrategy`. */
  static detect(
    options?: AutoStrategyOptions | undefined | null,
  ): Result<AutoStrategy, AuthFailure>;
  /** Retrieve a valid access token, refreshing or re-authenticating as needed. */
  getToken(): Promise<Result<TokenResult, AuthFailure>>;
}

/**
 * An auth strategy that uses a static access key for service-to-service
 * or CI/CD authentication.
 */
export declare class AccessKeyStrategy {
  /**
   * Create a new `AccessKeyStrategy` for the given workspace CRN and access key.
   * The CRN format is `crn:<region>:<workspace-id>`. A workspace mismatch fails
   * `getToken()` with `failure.type === "WORKSPACE_MISMATCH"`.
   */
  static create(
    workspaceCrn: string,
    accessKey: string,
  ): Result<AccessKeyStrategy, AuthFailure>;
  /** Retrieve a valid access token, refreshing or re-authenticating as needed. */
  getToken(): Promise<Result<TokenResult, AuthFailure>>;
}

/**
 * An auth strategy that uses OAuth refresh tokens persisted to disk
 * (`~/.cipherstash/auth.json`).
 */
export declare class DeviceSessionStrategy {
  /** Load credentials from the default profile store. */
  static fromProfile(): Result<DeviceSessionStrategy, AuthFailure>;
  /** Retrieve a valid access token, refreshing as needed. */
  getToken(): Promise<Result<TokenResult, AuthFailure>>;
}

/**
 * An auth strategy that federates a third-party OIDC JWT (Clerk, Supabase, …)
 * into a CipherStash CTS service token via `/api/authorise`.
 */
export declare class OidcFederationStrategy {
  /**
   * Create an `OidcFederationStrategy` for the given workspace CRN. `getJwt` is
   * called on every federation and must resolve to the current third-party OIDC
   * JWT. `baseUrl` pins the strategy to a specific CTS host.
   */
  static create(
    workspaceCrn: string,
    getJwt: () => Promise<string> | string,
    baseUrl?: string | undefined | null,
  ): Result<OidcFederationStrategy, AuthFailure>;
  /**
   * Like `create` but persists the federated CTS token through `loadToken` /
   * `saveToken` (e.g. an HTTP-only cookie) so it survives across requests.
   */
  static createWithStore(
    workspaceCrn: string,
    getJwt: () => Promise<string> | string,
    loadToken: () => Promise<string | null | undefined> | string | null | undefined,
    saveToken: (json: string) => Promise<void> | void,
    baseUrl?: string | undefined | null,
  ): Result<OidcFederationStrategy, AuthFailure>;
  /** Retrieve a valid CTS service token, federating or re-federating as needed. */
  getToken(): Promise<Result<TokenResult, AuthFailure>>;
}

/** The pending state of an in-progress OAuth 2.0 Device Authorization flow. */
export declare class DeviceCodeResult {
  get userCode(): string;
  get verificationUri(): string;
  get verificationUriComplete(): string;
  get expiresIn(): number;
  /**
   * Poll the auth server until the user completes authorization. **Consumes**
   * the internal handle — a second call fails with
   * `failure.type === "ALREADY_CONSUMED"`.
   */
  pollForToken(): Promise<Result<AuthResult, AuthFailure>>;
  /** Open the verification URI in the user's default browser. Non-consuming. */
  openInBrowser(): Result<boolean, AuthFailure>;
}

/** Begin the OAuth 2.0 Device Authorization flow. */
export declare function beginDeviceCodeFlow(
  region: string,
  clientId: string,
): Promise<Result<DeviceCodeResult, AuthFailure>>;

/** Provision a device client in ZeroKMS after login. */
export declare function bindClientDevice(): Promise<Result<void, AuthFailure>>;

/**
 * Deprecated alias for {@link DeviceSessionStrategy}, exported at runtime as
 * `module.exports.OAuthStrategy = DeviceSessionStrategy`.
 *
 * @deprecated Renamed to `DeviceSessionStrategy`.
 */
export declare const OAuthStrategy: typeof DeviceSessionStrategy;