# Session Runtime Contract

## Canonical Internal gRPC Operations

`IdentityRuntime` now exposes the canonical session operations consumed by `thalos-bff`:

- `StartIdentitySession`
- `RefreshIdentitySession`
- `IssueIdentityToken` (compatibility)
- `EvaluateIdentityPolicy` (policy guardrail)

## Session Flow

1. BFF calls `StartIdentitySession` with subject/tenant/provider/external token.
2. For `Google`, service exchanges and validates external token claims (`sub`, `aud`, `iss`) before issuing session tokens.
3. Service issues access token through existing token orchestration.
4. Service generates refresh token through provider-agnostic session token codec.
5. BFF calls `RefreshIdentitySession` with refresh token.
6. Service validates refresh token signature/expiry and reissues session tokens.

## Provider-Agnostic Secret Boundary

Session refresh token signing is bound to `IIdentitySecretMaterialProvider`.

- Contract is provider-neutral.
- Runtime binding is configuration-based by default.
- Vault/cloud/env adapters can be swapped at DI boundaries without changing use-case code.
- OIDC provider material uses the same boundary (no provider SDK coupling in use-case logic).
- Missing secrets fail explicitly at runtime; the service no longer falls back to a baked-in signing secret.
- `AddThalosServiceRuntime()` only provides a local in-memory session-signing default when no host configuration is present, so isolated tests and developer runs stay deterministic without changing production behavior.

## Configuration Keys

- `ThalosIdentity:Secrets:SessionSigning`
- `ThalosIdentity:Secrets:Oidc:Google:ClientId`
- `ThalosIdentity:Secrets:Oidc:Google:Issuer` (optional, defaults to `https://accounts.google.com`)
- `ThalosIdentity:Secrets:Default` (fallback)

## Production Expectation

- Production hosts must provide `ThalosIdentity:Secrets:SessionSigning`.
- Google OIDC validation must provide `ThalosIdentity:Secrets:Oidc:Google:ClientId`.
- The optional `Default` key is intended for non-sensitive shared local/test values, not as a production substitute for explicit signing material.