import { AuthStrategy } from '@voltro/protocol';

/** Loose shape for OIDC claims. The framework only reads `sub`
 *  natively; the rest is provider-specific. Apps cast to their own
 *  typed shape via `metadata.claims as MyIdpClaims`. */
export declare interface OidcClaims {
    readonly sub: string;
    readonly iss?: string;
    readonly aud?: string | ReadonlyArray<string>;
    readonly email?: string;
    readonly email_verified?: boolean;
    readonly [key: string]: unknown;
}

export declare const oidcStrategy: (options: OidcStrategyOptions) => AuthStrategy;

export declare interface OidcStrategyOptions {
    /**
     * Stable identifier used in logs + on
     * `Subject.metadata.provider`. Distinguishes one OIDC IdP from
     * another in multi-strategy setups (`'okta'`, `'keycloak'`,
     * `'cognito'`, …). Required because OIDC doesn't dictate a name.
     */
    readonly id: string;
    /**
     * The IdP's issuer URL. Used for two things:
     *   1. As the expected `iss` claim on incoming JWTs.
     *   2. As the base for OIDC discovery when `discoveryUrl` is not
     *      explicitly set: `${issuer}/.well-known/openid-configuration`.
     */
    readonly issuer: string;
    /**
     * Expected `aud` claim. Most IdPs set audience to your client id
     * (Okta, Auth0) or your API identifier (Cognito, custom OIDC).
     * Pass an array for IdPs that issue tokens with multiple audiences.
     */
    readonly audience?: string | ReadonlyArray<string>;
    /**
     * Explicit JWKS URL — skips OIDC discovery entirely. Use when the
     * provider documents the URL and you want zero boot-time IO.
     */
    readonly jwksUrl?: string;
    /**
     * OIDC discovery document URL. Defaults to
     * `${issuer}/.well-known/openid-configuration`. Set explicitly if
     * the provider hosts it at a non-standard path.
     */
    readonly discoveryUrl?: string;
    /**
     * JWT algorithm allowlist. Defaults to `['RS256']` (the OIDC
     * spec's MUST). Extend when the provider signs with ES256 / PS256
     * / EdDSA.
     */
    readonly algorithms?: ReadonlyArray<'ES256' | 'RS256' | 'PS256' | 'EdDSA'>;
    /**
     * Cookie name when the JWT travels as a cookie (server-rendered
     * apps, cookie-mode SDKs). Pass `null` to disable cookie fallback.
     */
    readonly cookieName?: string | null;
    /**
     * Which claim carries the Voltro `tenantId`. Defaults to `'tenant'`.
     * IdPs commonly use custom claims under their own URN namespace —
     * Auth0 uses `'https://yourapp/tenant'`, Cognito uses
     * `'custom:tenant_id'`, Okta uses `'acme/tenant_id'` or similar.
     * Set this to the exact claim name your provider issues.
     */
    readonly tenantClaim?: string;
    /**
     * Map JWT claims → tenantId. Overrides `tenantClaim`. Use when
     * the tenant identity needs derivation (e.g. join two claims, or
     * lookup via a static map). Returning `null` is treated as
     * `failed` — the strategy IS the request's owner but can't satisfy
     * the tenant invariant.
     */
    readonly tenantIdFromClaims?: (claims: OidcClaims) => string | null;
    /**
     * Fallback tenant id when the configured claim is absent. Most
     * apps use this for single-tenant OIDC integrations.
     */
    readonly defaultTenantId?: string;
    /**
     * Map verified OIDC claims → the subject's permission scopes. Lands
     * on `Subject.scopes` so `requireScope` / `hasScope` gate handlers
     * off the token with no second lookup. The OAuth `scope` claim is a
     * space-delimited string (`(c) => String(c.scope ?? '').split(' ').filter(Boolean)`);
     * many IdPs also emit a `roles` / `groups` / `permissions` array.
     * Omitted → no scopes (a scope gate then denies).
     */
    readonly scopesFromClaims?: (claims: OidcClaims) => ReadonlyArray<string>;
}

export { }