import { SecretRefParseError, SecretRefParseErrorKind } from "./errors.js";
import { SecretRef } from "@graphorin/core/contracts";

//#region src/secrets/secret-ref.d.ts

/**
 * Set of scheme names the parser knows about by default. Every entry
 * corresponds to a built-in resolver shipped from `./resolvers/`.
 *
 * @stable
 */
declare const BUILTIN_SCHEMES: ReadonlyArray<string>;
/**
 * Schemes that **forbid** an authority component (no `//` allowed).
 *
 * @stable
 */
declare const OPAQUE_ONLY_SCHEMES: ReadonlySet<string>;
/**
 * Schemes whose authority component is optional. `file:` and
 * `encrypted-file:` accept either `file:///abs/path` (authority empty)
 * or `file:relative/path` (opaque). `vault://` accepts both an explicit
 * server (`vault://host:port/...`) and an opaque form that defers to
 * the `VAULT_ADDR` environment variable.
 *
 * @stable
 */
declare const AUTHORITY_OPTIONAL_SCHEMES: ReadonlySet<string>;
/**
 * Internal parsed shape for a single `SecretRef` URI. Conforms to the
 * cross-package `SecretRef` contract declared in `@graphorin/core` and
 * adds nothing on top of it - richer access (split authority, per-key
 * multi-value query) is exposed through dedicated helpers below.
 *
 * @stable
 */
interface ParsedSecretRef extends SecretRef {
  readonly raw: string;
  readonly scheme: string;
  readonly authority?: string;
  readonly path: string;
  readonly query: Readonly<Record<string, string>>;
  readonly fragment?: string;
}
/**
 * Result of `validateSecretRefs(...)`. Lists every problem found during
 * a recursive walk over a config object.
 *
 * @stable
 */
interface SecretRefValidationResult {
  readonly ok: boolean;
  readonly issues: ReadonlyArray<{
    readonly path: ReadonlyArray<string | number>;
    readonly raw: unknown;
    readonly error: SecretRefParseError;
  }>;
}
/**
 * Options for `validateSecretRefs(...)`.
 *
 * @stable
 */
interface ValidateSecretRefsOptions {
  /**
   * Allow `literal:` refs in the input. Off by default - `literal:` is
   * gated by the resolver, but validation can fail-fast as well.
   */
  readonly allowLiteral?: boolean;
  /**
   * Names of fields that should be treated as `*Ref` strings. Defaults
   * to a heuristic match: any string-valued field whose key ends in
   * `Ref`, `_ref`, `REF`, or `_REF`.
   */
  readonly fieldNameMatcher?: (key: string) => boolean;
  /**
   * Restrict the accepted scheme set. Defaults to `BUILTIN_SCHEMES`
   * plus any scheme registered through `registerResolver(...)`.
   */
  readonly knownSchemes?: ReadonlyArray<string>;
}
/**
 * Strict RFC 3986-subset parser for `SecretRef` URIs. Rejects every
 * input that does not conform to the grammar declared in the
 * architecture spec; never silently falls back to a default scheme.
 *
 * @stable
 */
declare function parseSecretRef(uri: string): ParsedSecretRef;
/**
 * Split an authority string of the form `[userinfo@]host[:port]` into
 * its components. `host` is lowercased per RFC 3986; userinfo and port
 * are returned verbatim. Returns `undefined` if the authority is empty.
 *
 * @stable
 */
declare function parseAuthority(authority: string): {
  readonly userinfo?: string;
  readonly host: string;
  readonly port?: number;
} | undefined;
/**
 * Read a single query parameter from a parsed ref. Returns `undefined`
 * if the parameter is not present.
 *
 * @stable
 */
declare function getQueryParam(ref: ParsedSecretRef, key: string): string | undefined;
/**
 * Read a query parameter and throw if it is missing. Useful for
 * resolver implementations that require a configuration value.
 *
 * @stable
 */
declare function getQueryParamRequired(ref: ParsedSecretRef, key: string): string;
/**
 * Read every value associated with `key` in the original query string
 * (multi-value support). Returns an empty array if the parameter is
 * not present.
 *
 * @stable
 */
declare function getQueryParamAll(ref: ParsedSecretRef, key: string): ReadonlyArray<string>;
/**
 * Walks an arbitrary configuration object and validates every `*Ref`
 * field. Returns a structured result rather than throwing, so callers
 * can collect every issue before deciding to bail out.
 *
 * @stable
 */
declare function validateSecretRefs(config: unknown, opts?: ValidateSecretRefsOptions): SecretRefValidationResult;
/**
 * Reject naked strings (no scheme) at validation time. Used by the
 * resolver dispatcher so a typo in `*Ref` config does not silently fall
 * through to a default scheme.
 *
 * @stable
 */
declare function assertNotNakedString(input: string): void;
/**
 * Convenience: parse if the input looks like a URI, otherwise throw a
 * `naked-string` parse error. Used by `resolveSecret(...)`.
 *
 * @stable
 */
declare function parseOrAssert(input: string): ParsedSecretRef;
/**
 * Map `SecretRefParseErrorKind` to a human-friendly string. Useful for
 * diagnostic messages in `graphorin doctor --check-secrets`.
 *
 * @stable
 */
declare function describeParseErrorKind(kind: SecretRefParseErrorKind): string;
//#endregion
export { AUTHORITY_OPTIONAL_SCHEMES, BUILTIN_SCHEMES, OPAQUE_ONLY_SCHEMES, ParsedSecretRef, SecretRefValidationResult, ValidateSecretRefsOptions, assertNotNakedString, describeParseErrorKind, getQueryParam, getQueryParamAll, getQueryParamRequired, parseAuthority, parseOrAssert, parseSecretRef, validateSecretRefs };
//# sourceMappingURL=secret-ref.d.ts.map