Idea: opt-in TrustContract for OIDC provider configuration

[61465]

Idea: opt-in TrustContract for OIDC provider configuration

opening this as a Discussion (not a formal RFC issue) to float the shape and gather feedback before committing to a scope. the companion reliability fix for the error-flattening side of this is already in flight at #4626; this is the orthogonal "trust shape" piece.

one-line

add an optional *TrustContract pointer on oidc.ProviderConfig that lets operators declare their policy for email_verified, acr, amr per provider. nil pointer = current behavior exactly. non-nil = declarative gate before newIdentityFromClaims.

why

Kratos already defends against nOAuth-class account linking through three implicit layers (OIDCUniqueID credential indexing, password.identifier uniqueness, duplicate-flow password gate). the defense works — but it is implicit, scattered across identity/credentials_oidc.go:98, the default identity schema, and selfservice/strategy/oidc/strategy.go:702-731. operators who need to prove to auditors "we're not vulnerable to nOAuth" today walk reviewers through three code locations. a declarative per-provider contract would make that single-artifact.

three in-tree providers also silently set EmailVerified: true on claims the provider does not actually verify (provider_facebook.go:120-122, provider_slack.go:87, provider_discord.go:98), and no consumer code reads the field — so the lie is harmless today but would be surprising to anyone who later tries to add a gate.

#4581 showed the generic "any error becomes 401" pattern on the reliability side; the same code area has the orthogonal "any claim becomes trusted" pattern on the trust side. this discussion proposes the declarative fix for the second one.

sketch

selfservice:
  methods:
    oidc:
      config:
        providers:
          - id: google
            provider: google
            trust_contract:
              verified_email_policy: require    # google always mints the claim
              acceptable_amr: ["mfa", "hwk"]    # admins must MFA
          - id: facebook
            provider: facebook
            # no trust_contract → current behavior preserved

type TrustContract struct {
    VerifiedEmailPolicy VerifiedEmailPolicy // "", "require", "attest"
    AcceptableACR []string
    AcceptableAMR []string
    ClaimsAreVerifiedByProvider []string
}

func (c *TrustContract) Enforce(ctx context.Context, claims *Claims) error {
    if c == nil { return nil }  // the whole guarantee of backward-compat
    // ... policy evaluation; herodot error with stable ID on reject ...
}

one guard, called once between claims parsing and newIdentityFromClaims. ~200 LOC total including validation + tests.

what's drafted

i've written a longer draft offline (not pushing yet): main doc (3,500 words) + Go reference impl (~195 LOC) + 30+ unit tests + a docker-compose attack-sim PoC (shows before/after) + threat model (STRIDE+LINDDUN) + compliance mapping to SOC 2 / NIST / FedRAMP controls + benchmark harness + observability spec (prom metrics + otel span) + default contracts bundle for 11 providers.

happy to open any subset as a formal RFC issue or PR series. before i do, three questions where community input would most change the shape:

1. scope. is this a Kratos concern or should it live in Hydra? i've assumed Kratos because the consumer-side guard is what's missing; happy to be told otherwise.
2. shape. declarative (what i've drafted) vs executable hook (Auth0 Actions / Clerk Rules shape). the two are complementary; declarative seemed cheaper to review and audit.
3. defaults. my draft ships ignore for every provider (zero behavior change). should Google/Apple ship require by default in a later minor, or should every tightening always be operator-opt-in?

not asking for

• a decision today.
• any change to current behavior for existing deployments (that's the point of the pointer being optional).
• replacing jsonnet mappers (they run as before after the guard accepts).

author notes

• i'm the author of fix: don't flatten transient errors into 401 in whoami #4626 (the whoami error-classification fix). the two are intentionally decoupled: fix: don't flatten transient errors into 401 in whoami #4626 is a reliability fix, this is a trust-shape proposal.
• public context on the attack class: Vectra's 2023 nOAuth writeup (https://www.descope.com/blog/post/noauth), OIDC Core §5.7, and the sister proposal i filed to Node.js at security proposal: node:crypto.verifyOIDCClaims — stdlib primitive to close the OIDC Provider Trust Boundary bug class nodejs/security-wg#1593.
• open-source scanner for this class: https://github.com/61465/identity-trust-hunt
• all cited material is public. no private vulnerability info is reused here.

feedback welcome. will not open a formal RFC issue until #4626 has landed and this thread has a direction.