import { ScopeParseError } from "./errors.js";

//#region src/auth/scope.d.ts

/**
 * Result of `parseScope(...)`. The `kind` discriminator lets callers
 * branch between two- and three-segment scopes without re-parsing the
 * raw string.
 *
 * @stable
 */
type ParsedScope = {
  readonly kind: 'two-segment';
  readonly resource: string;
  readonly action: string;
  readonly raw: string;
} | {
  readonly kind: 'three-segment';
  readonly resource: string;
  readonly action: string;
  readonly target: string;
  readonly raw: string;
};
/**
 * Parse a single scope string. Throws `ScopeParseError` for any input
 * that does not match the canonical grammar; never silently coerces.
 *
 * @stable
 */
declare function parseScope(input: string): ParsedScope;
/**
 * Try-parse helper. Returns `undefined` on failure rather than
 * throwing; useful when iterating over a granted set that may include
 * legacy strings.
 *
 * @stable
 */
declare function tryParseScope(input: string): ParsedScope | undefined;
/**
 * Match a single granted scope against a single required scope.
 *
 * Rules:
 * - `admin:*` matches every scope.
 * - Resource segment: must be exact match.
 * - Action segment: exact match, or granted action `*` matches any
 *   required action.
 * - Optional target segment: a granted three-segment scope only
 *   matches a three-segment requirement; `*` in the granted target
 *   matches any required target. A granted two-segment scope matches
 *   a required three-segment scope when the resource and action align
 *   (a two-segment grant is broader than a three-segment grant).
 *
 * @stable
 */
declare function scopeMatches(granted: ParsedScope, required: ParsedScope): boolean;
/**
 * Match a granted set against a required scope. Strings inside
 * `granted` that fail to parse are skipped (they cannot grant
 * anything).
 *
 * @stable
 */
declare function scopeSetMatches(granted: ReadonlyArray<string | ParsedScope>, required: string | ParsedScope): boolean;
/**
 * Canonical catalogue of scopes recognised by the framework. Wider
 * deployments are free to introduce additional scope strings; the
 * catalogue exists so middleware authors can reference a single
 * source of truth and so the CLI can enumerate the well-known scopes
 * for tab-completion.
 *
 * @stable
 */
declare const SCOPE_CATALOGUE: ReadonlyArray<string>;
/**
 * Validate that every entry in a granted set is a syntactically valid
 * scope. Returns the parse errors collected during the walk, or an
 * empty array if every entry parsed.
 *
 * @stable
 */
declare function validateScopeSet(scopes: ReadonlyArray<string>): ReadonlyArray<ScopeParseError>;
//#endregion
export { ParsedScope, SCOPE_CATALOGUE, parseScope, scopeMatches, scopeSetMatches, tryParseScope, validateScopeSet };
//# sourceMappingURL=scope.d.ts.map