import { TokenFormatError } from "./errors.js";
import { Buffer } from "node:buffer";

//#region src/auth/token-format.d.ts

/** Default token prefix. Aligned with the framework name. */
declare const DEFAULT_TOKEN_PREFIX = "gph";
/** Canonical entropy length in bytes. 32 bytes = 256 bits. */
declare const TOKEN_ENTROPY_BYTES = 32;
/** Canonical entropy block length in characters when base62-encoded. */
declare const TOKEN_ENTROPY_LENGTH = 43;
/** Canonical CRC32 checksum length in characters when base62-encoded. */
declare const TOKEN_CHECKSUM_LENGTH = 6;
/** Version segment used by every token issued by this version of the framework. */
declare const TOKEN_VERSION: "v1";
/**
 * Set of accepted environment labels. The library keeps a small,
 * fixed set so deployments can rely on the label being a stable
 * routing signal. Operators can extend this by passing a custom
 * `acceptEnvironments` allowlist into `parseToken(...)`.
 *
 * @stable
 */
type TokenEnvironment = 'live' | 'test' | 'local';
/** Canonical accepted environments. Frozen so callers cannot mutate it. */
declare const TOKEN_ENVIRONMENTS: ReadonlyArray<TokenEnvironment>;
/**
 * Result of `parseToken(...)`. Splitting the parsed shape lets the
 * caller branch on the discriminated `ok` field without exception
 * plumbing on the verify hot path.
 *
 * @stable
 */
type ParsedToken = {
  readonly ok: true;
  readonly prefix: string;
  readonly env: string;
  readonly version: typeof TOKEN_VERSION;
  readonly entropy: string;
  readonly checksum: string;
  readonly raw: string;
} | {
  readonly ok: false;
  readonly reason: TokenFormatError;
};
/**
 * Options for `parseToken(...)`.
 *
 * @stable
 */
interface ParseTokenOptions {
  /** Override the accepted prefix. Defaults to `DEFAULT_TOKEN_PREFIX`. */
  readonly acceptPrefix?: string;
  /**
   * Override the accepted environments. Defaults to
   * `TOKEN_ENVIRONMENTS`. An empty array is treated as "accept any
   * non-empty lowercase ASCII label".
   */
  readonly acceptEnvironments?: ReadonlyArray<string>;
}
/**
 * Options for `generateRawToken(...)`.
 *
 * @stable
 */
interface GenerateRawTokenOptions {
  /** Token prefix. Defaults to `DEFAULT_TOKEN_PREFIX`. */
  readonly prefix?: string;
  /** Environment label. */
  readonly env: TokenEnvironment | string;
}
/**
 * CRC32/IEEE 802.3 implementation. Pure JS, branchless inner loop -
 * matches the polynomial used by GZIP / PNG / Ethernet (`0xEDB88320`).
 * Returns an unsigned 32-bit integer so it can be base62-encoded
 * without further bit-fiddling.
 *
 * @stable
 */
declare function crc32(input: Uint8Array | string): number;
/**
 * Encode a non-negative integer (≤ 2^53 - 1) as base62. The output is
 * left-padded with `'0'` to the requested width. Throws on negative,
 * non-finite, or width-exceeding inputs to avoid silent truncation.
 *
 * @stable
 */
declare function encodeBase62Integer(value: number, width: number): string;
/**
 * Encode a byte buffer as base62 with a fixed-length output. The
 * routine treats the bytes as a big-endian unbounded integer and
 * left-pads to `width` so that any 32-byte input yields exactly 43
 * base62 characters.
 *
 * Bias note (CodeQL `js/biased-cryptographic-random`): this is **not** a
 * `byte % 62` reduction over CSPRNG bytes - that would indeed bias the
 * output. Instead we perform full big-integer long division, so each
 * emitted base62 character represents a distinct "digit" of the input
 * integer in base 62. As long as the input is uniform over `[0, 256^n)`
 * (which is what `crypto.randomBytes(n)` guarantees), the resulting
 * base62 string is uniform over `[0, 62^width)` for the leading
 * positions; only the most-significant position can carry a small bias
 * when `256^n` is not an exact power of 62, and that position is what
 * `width` left-pads to a constant length for. Callers that need
 * fixed-entropy tokens should pick `n` such that `256^n >= 62^width` -
 * the existing `encodeRandomToken` helpers do.
 *
 * @stable
 */
declare function encodeBase62Bytes(bytes: Uint8Array, width: number): string;
/**
 * Generate a brand-new raw token. The result is the only place the
 * plaintext value exists; callers MUST hand it to the user immediately
 * and persist only the HMAC hash via the `AuthTokenStore` contract.
 *
 * @stable
 */
declare function generateRawToken(opts: GenerateRawTokenOptions): {
  readonly raw: string;
  readonly entropyBytes: Buffer;
};
/**
 * Strict structural parser. Returns a discriminated union so callers
 * can branch on `ok` without throwing on the hot path. The function
 * never logs the raw input; the error class only carries the input
 * length.
 *
 * @stable
 */
declare function parseToken(input: string, opts?: ParseTokenOptions): ParsedToken;
/**
 * Cheap structural pre-filter used before doing any HMAC or DB work.
 * Identical to `parseToken` but returns the boolean shape that the
 * verify pipeline expects.
 *
 * @stable
 */
declare function verifyOffline(input: string, opts?: ParseTokenOptions): {
  readonly ok: true;
  readonly env: string;
} | {
  readonly ok: false;
  readonly reason: string;
};
//#endregion
export { DEFAULT_TOKEN_PREFIX, GenerateRawTokenOptions, ParseTokenOptions, ParsedToken, TOKEN_CHECKSUM_LENGTH, TOKEN_ENTROPY_BYTES, TOKEN_ENTROPY_LENGTH, TOKEN_ENVIRONMENTS, TOKEN_VERSION, TokenEnvironment, crc32, encodeBase62Bytes, encodeBase62Integer, generateRawToken, parseToken, verifyOffline };
//# sourceMappingURL=token-format.d.ts.map