@kindgi/api 0.1.4 → 0.1.5

package/src/flow-binding.ts

@@ -72,6 +72,8 @@ export interface FlowRegistryBinding {
    * well-formed `Flow`. Bindings MAY reject with `already-registered`
    * when the same `(flowId, version)` is re-published; the route maps
    * that to `409`.
+   * A version of a flow whose versions live in another project is
+   * `project-mismatch` (flows never move between projects; `409 flow-project-mismatch`).
    */
   publish(input: FlowPublishInput): Promise<FlowPublishOutcome>;
   /**
@@ -93,6 +95,11 @@ export interface FlowRegistryBinding {
 export type FlowVersionRecord = Flow & {
   /** ISO-8601; present only on an unregistered version. */
   readonly unregisteredAt?: string;
+  /**
+   * The project the version belongs to, when the store records it: a
+   * deploy into another project is refused even when it writes nothing.
+   */
+  readonly projectId?: ProjectId;
 };
 
 export interface FlowListInput {
@@ -209,6 +216,18 @@ export type FlowPublishOutcome =
       readonly flowId: FlowId;
       readonly version: string;
       readonly projectId: ProjectId;
+    }
+  | {
+      /**
+       * The flow's versions live in another project: a flow belongs to
+       * the project its first version was published into, and never
+       * moves. Nothing is written (the route answers `409 flow-project-mismatch`).
+       */
+      readonly kind: 'project-mismatch';
+      readonly flowId: FlowId;
+      readonly version: string;
+      /** The project the flow belongs to. */
+      readonly projectId: ProjectId;
     };
 
 export type FlowUnregisterOutcome = {

package/src/flow-pins.ts

@@ -113,17 +113,33 @@ export async function publishDeployedFlow(
   input: PublishDeployedFlowInput,
 ): Promise<DeployedVersionOutcome> {
   const { flows, tenantId, projectId, flow, pins, enqueueTuples } = input;
+  const existing = await allFlowVersions(flows, tenantId, flow.id);
+  // A flow never moves, even by a deploy that writes nothing (an unchanged
+  // or reused version): one of another project is refused. A registry
+  // that doesn't record the project refuses only a write.
+  const held = existing[0];
+  if (held !== undefined) {
+    const record = await flows.getVersion({ tenantId, flowId: flow.id, version: held.version });
+    if (record?.projectId !== undefined && record.projectId !== projectId) {
+      throw new PublishRefused('flow', `${flow.id}@${flow.version}`, {
+        kind: 'project-mismatch',
+        flowId: flow.id,
+        version: flow.version,
+        projectId: record.projectId,
+      });
+    }
+  }
   return deployVersion<Flow>({
     label: `flow "${flow.id as unknown as string}"`,
     definition: flow,
     pins,
     pinsDigest: flowPinsDigest(pins),
-    existing: await allFlowVersions(flows, tenantId, flow.id),
+    existing,
     publish: async (version) => {
       const outcome = await flows.publish({ tenantId, projectId, flow: version, enqueueTuples });
       if (outcome.kind === 'ok') return 'ok';
       if (outcome.kind === 'already-registered') return 'taken';
-      throw new PublishRefused('flow', `${flow.id}@${version.version}`, outcome.kind);
+      throw new PublishRefused('flow', `${flow.id}@${version.version}`, outcome);
     },
   });
 }

package/src/gate.ts

@@ -4,6 +4,7 @@
 import type { ReviewerRole } from '@kindgi/authz';
 import type { LiveScope } from '@kindgi/types';
 
+import type { EvalSample } from './eval-run-binding.js';
 import type { GateMetricName, GateMetricSpec, GatePolicySpec } from './gate-policy-binding.js';
 import type { ComparisonMetric, JudgedComparisonSummary } from './judged-dispatcher.js';
 
@@ -114,6 +115,7 @@ export function evaluateGate(input: GateInput): GateResult {
     checks.push(freshnessCheck(spec.comparison.maxAgeHours, summary, input.now));
   }
   if (spec.comparison?.suite !== undefined) checks.push(suiteCheck(spec.comparison.suite, summary));
+  if (summary.sample !== undefined) checks.push(sampleCheck(summary.sample));
   checks.push(sameContentsCheck(input));
   checks.push(baselineCheck(summary, input));
   checks.push(scopeCheck(summary, input));
@@ -204,6 +206,23 @@ function suiteCheck(
   };
 }
 
+/**
+ * A comparison on part of the test set: the hold-out part proves a
+ * candidate; the search part chose it, so its numbers flatter it.
+ */
+function sampleCheck(sample: EvalSample): GateCheck {
+  const passed = sample.part === 'hold-out';
+  return {
+    name: 'comparison.sample',
+    passed,
+    message: passed
+      ? `The comparison ran the hold-out part of the test set (seed ${sample.seed}).`
+      : 'The comparison ran the search part of the test set, which chose this candidate: compare on the hold-out part, or the whole test set.',
+    value: sample.part,
+    threshold: 'hold-out',
+  };
+}
+
 function sameContentsCheck(input: GateInput): GateCheck {
   const { promotion, summary } = input;
   const candidate = summary?.candidate;
@@ -217,6 +236,13 @@ function sameContentsCheck(input: GateInput): GateCheck {
     };
   }
   const compared = `${candidate.agentId} ${candidate.version}`;
+  if (candidate.overrides !== undefined) {
+    return {
+      name,
+      passed: false,
+      message: `The comparison ran ${compared} with other content for ${[...(candidate.overrides.settings ?? []), ...(candidate.overrides.prompts ?? [])].join(', ')} than it pins (an improvement pass's search): compare the published version.`,
+    };
+  }
   if (candidate.agentId !== promotion.agentId || candidate.version !== promotion.version) {
     return {
       name,

package/src/handler-binding.ts

@@ -2,7 +2,9 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { AgentId } from '@kindgi/agents';
+import type { Principal } from '@kindgi/authz';
 import type { FlowVersionOverrides } from '@kindgi/flow';
+import type { RunIdempotencyKey, RunTriggerRef } from '@kindgi/runtime';
 import type { FlowId, ProjectId, RunId, ScopeSegment, Semver, TenantId } from '@kindgi/types';
 
 /**
@@ -67,6 +69,12 @@ export interface RunTrace {
 export interface ResumeRunBindingInput {
   readonly tenantId: TenantId;
   readonly runId: RunId;
+  /**
+   * The trace context of the request resuming the run (a reviewer's
+   * decision): the resumed work runs under it, and the run keeps its own
+   * trace id from the request that started it. Absent: as before.
+   */
+  readonly trace?: RunTrace;
 }
 
 export interface InvokeAgentBindingInput {
@@ -107,6 +115,19 @@ export interface InvokeAgentBindingInput {
    * can't run in the background may treat `false` like `true`.
    */
   readonly wait?: boolean;
+  /**
+   * Start the run at most once per key (`RunIdempotencyKey`): a key a run
+   * already has starts nothing and answers that run, with `existing`.
+   */
+  readonly idempotencyKey?: RunIdempotencyKey;
+  /** Set when a trigger starts the run; the run records it (`RunTriggerRef`). */
+  readonly trigger?: RunTriggerRef;
+  /**
+   * Who started the run (the authenticated caller), when known: whom the
+   * turn acts for, e.g. whose own memory its retrievals may read. Set by
+   * the route, never from the body. On its own it enforces nothing.
+   */
+  readonly principal?: Principal;
   /** The trace context of the request starting the run: the binding records its `traceId` on the run. */
   readonly trace?: RunTrace;
 }
@@ -128,14 +149,28 @@ export interface InvokeFlowBindingInput {
    * can't run in the background may treat `false` like `true`.
    */
   readonly wait?: boolean;
+  /**
+   * Start the run at most once per key (`RunIdempotencyKey`): a key a run
+   * already has starts nothing and answers that run, with `existing`.
+   */
+  readonly idempotencyKey?: RunIdempotencyKey;
+  /** Set when a trigger starts the run; the run records it (`RunTriggerRef`). */
+  readonly trigger?: RunTriggerRef;
   /** Agents and tools to run at other exact versions than the flow version's pins (`RunFlowInput.versions`). */
   readonly versions?: FlowVersionOverrides;
+  /** Who started the run, as for `InvokeAgentBindingInput.principal`: its agent steps act for them. */
+  readonly principal?: Principal;
   /** The trace context of the request starting the run, as for an agent run. */
   readonly trace?: RunTrace;
 }
 
 export type RunHandlerOutcome =
-  | { readonly kind: 'ok'; readonly runId: RunId }
+  | {
+      readonly kind: 'ok';
+      readonly runId: RunId;
+      /** The `idempotencyKey` named a run that already existed: nothing new started. */
+      readonly existing?: true;
+    }
   | { readonly kind: 'err'; readonly error: RunHandlerFailure };
 
 /**

package/src/hitl-binding.ts

@@ -88,17 +88,41 @@ export interface ListApprovalsBindingInput {
   readonly status?: ApprovalStatus;
   readonly requiredRole?: ReviewerRole;
   readonly since?: Timestamp;
+  /** A bare time: approvals created before it. Milliseconds, no tie-breaker; `after` replaces it. */
   readonly cursor?: Cursor;
   /**
    * Only approvals whose `waitTokenId` is one of these: the approvals a
    * run's open waits belong to (T272). Absent: no filter.
    */
   readonly waitTokenIds?: readonly string[];
+  /**
+   * Only approvals after this one in the list's order (`createdAt` desc,
+   * then `id` desc): where a page that ended on it continues. Its
+   * `createdAt` is the binding's `exactCreatedAt` for it.
+   */
+  readonly after?: ApprovalPosition;
+}
+
+/**
+ * Where a page of approvals ends: an approval's `createdAt` as stored
+ * (Postgres keeps microseconds), and its id. A JS `Date` keeps
+ * milliseconds: a position built from one skips the approvals created
+ * earlier in the same millisecond.
+ */
+export interface ApprovalPosition {
+  readonly createdAt: string;
+  readonly id: ApprovalId;
 }
 
 export interface ListApprovalsBindingResult {
   readonly approvals: readonly Approval[];
   readonly nextCursor?: Cursor;
+  /**
+   * Each listed approval's `createdAt` as stored (microseconds), by id:
+   * with the id, the `after` that continues past it. Absent from a binding
+   * that doesn't give it; a caller then continues by `cursor`.
+   */
+  readonly exactCreatedAt?: Readonly<Record<string, string>>;
 }
 
 export interface SubmitReviewBindingInput {

package/src/identity-directory-binding.ts

@@ -13,16 +13,16 @@ import type { Cursor, TenantId, Timestamp, UserId } from '@kindgi/types';
  * tenant" / "show me a user's profile" / "revoke all a user's active
  * sessions" question this binding covers.
  *
- * Registry-only over HTTP — the framework does NOT own user
- * persistence. Deployments plug in an LDAP / SCIM / IdP-mirror /
- * bespoke store behind this binding.
+ * The framework does NOT own user persistence. Deployments plug in an
+ * LDAP / SCIM / IdP-mirror / bespoke store behind this binding.
  *
  * Same caller-plugged pattern as every other admin-plane binding
  * (`PolicyRegistryBinding`, `ProviderRegistryBinding`, ...).
  *
  * The directory is flat. Groups / roles / RBAC / invitations /
  * audit history / LDAP+SCIM sync / impersonation are not part of this
- * binding.
+ * binding. Adding a person (`createUser`) is optional: a directory that
+ * mirrors an identity provider leaves it out.
  */
 export interface IdentityDirectoryBinding {
   /**
@@ -30,6 +30,14 @@ export interface IdentityDirectoryBinding {
    * the route surfaces `null` as `404 identity-user-not-found`.
    */
   getUser(input: IdentityGetUserInput): Promise<UserRecord | null>;
+  /**
+   * Optional. The person still in the tenant whose `primaryEmail` is
+   * `email`, compared as the directory compares emails when it adds a
+   * person (case-insensitively, for the runtime's); `null` when none.
+   * When present, `POST /v1/projects/{projectId}/memberships` takes an
+   * `email` as well as a `userId`.
+   */
+  findUserByEmail?(input: IdentityFindUserByEmailInput): Promise<UserRecord | null>;
   /**
    * Cursor-paginated list of users in the tenant. Optional `query`
    * is a prefix match on `displayName` — the natural filter shape
@@ -55,19 +63,88 @@ export interface IdentityDirectoryBinding {
    * delegate to `SessionStoreBinding.revokeAllForUser`.
    */
   revokeAllSessions(input: IdentityRevokeSessionsInput): Promise<RevokeSessionsResult>;
+  /**
+   * Optional. Add a person to the tenant as a tenant member, written to
+   * the authorization store before it returns: they can read the
+   * tenant's settings, not its projects. A tenant admin then gives them a
+   * role and mints their first API key. When present,
+   * `POST /v1/identity/users` mounts (tenant admins only). An email
+   * another person of the tenant has is refused.
+   */
+  createUser?(input: IdentityCreateUserInput): Promise<IdentityCreateUserResult>;
+  /**
+   * Optional. Unregister a person (remove them from the tenant), in one
+   * step: they're marked unregistered (their record stays, with
+   * `unregisteredAt`, so their history still says who they were), every
+   * API key and session of theirs is revoked, and every grant and
+   * membership they hold is taken from the authorization store, all before
+   * it returns. Their email is then free: adding it again makes a new
+   * person. Unregistering someone already unregistered changes nothing.
+   * Refused for yourself, the deployment's seed user, and the tenant's
+   * only tenant admin. When present,
+   * `POST /v1/identity/users/{userId}/unregister` mounts (tenant admins
+   * only).
+   */
+  unregisterUser?(input: IdentityUnregisterUserInput): Promise<IdentityUnregisterUserResult>;
+}
+
+export interface IdentityUnregisterUserInput {
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+  /** Who unregisters them: `user:<id>` or `service_account:<id>`. */
+  readonly unregisteredBy?: string;
 }
 
+/** Why a person can't be unregistered. */
+export type IdentityUnregisterUserRefusal = 'yourself' | 'seed-user' | 'last-tenant-admin';
+
+export type IdentityUnregisterUserResult =
+  | {
+      readonly kind: 'unregistered';
+      /** The person, with `unregisteredAt`. */
+      readonly user: UserRecord;
+      /** What unregistering took away (each 0 when they were already unregistered). */
+      readonly keysRevoked: number;
+      readonly sessionsRevoked: number;
+      readonly grantsRemoved: number;
+    }
+  | { readonly kind: 'not-found' }
+  | {
+      readonly kind: 'refused';
+      readonly reason: IdentityUnregisterUserRefusal;
+      readonly message: string;
+    };
+
+export interface IdentityCreateUserInput {
+  readonly tenantId: TenantId;
+  readonly displayName: string;
+  readonly primaryEmail?: string;
+  /** Who added them: `user:<id>` or `service_account:<id>`. */
+  readonly createdBy?: string;
+}
+
+export type IdentityCreateUserResult =
+  | { readonly kind: 'created'; readonly user: UserRecord }
+  | { readonly kind: 'email-taken'; readonly userId: UserId };
+
 export interface IdentityGetUserInput {
   readonly tenantId: TenantId;
   readonly userId: UserId;
 }
 
+export interface IdentityFindUserByEmailInput {
+  readonly tenantId: TenantId;
+  readonly email: string;
+}
+
 export interface IdentityListUsersInput {
   readonly tenantId: TenantId;
   readonly limit: number;
   readonly cursor?: Cursor;
   /** Prefix match on `UserRecord.displayName`. Undefined = no filter. */
   readonly query?: string;
+  /** Unregistered people too (`unregisteredAt` set). Default: only the people still here. */
+  readonly includeUnregistered?: boolean;
 }
 
 export interface IdentityListSessionsInput {
@@ -78,6 +155,8 @@ export interface IdentityListSessionsInput {
 export interface IdentityRevokeSessionsInput {
   readonly tenantId: TenantId;
   readonly userId: UserId;
+  /** Who asked (`user:<id>`, `service_account:<id>`), for the audit trail. */
+  readonly revokedBy?: string;
 }
 
 /**
@@ -94,6 +173,8 @@ export interface UserRecord {
   readonly displayName?: string;
   readonly createdAt: Timestamp;
   readonly lastActiveAt?: Timestamp;
+  /** When they were removed from the tenant (`unregisterUser`); absent while they're here. */
+  readonly unregisteredAt?: Timestamp;
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
 

package/src/identity-provider-binding.ts

@@ -4,35 +4,216 @@
 import type { TenantId } from '@kindgi/types';
 
 /**
- * Caller-plugged catalog of OAuth 2.0 / OIDC identity providers the
- * deployment offers to its tenants. Same pattern as
- * `ProviderRegistryBinding` (model providers) — the API package does
- * NOT own provider persistence, and secrets never cross the wire.
+ * Caller-plugged catalog of the identity providers a tenant signs in
+ * with: OIDC and SAML identity providers (sign-in), and plain OAuth 2.0
+ * providers. Same pattern as `ProviderRegistryBinding` (model providers):
+ * the API package does NOT own provider persistence, and secrets never
+ * cross the wire.
  *
- * A `ProviderConfig` carries ONLY a `clientSecretRef` — an opaque
- * pointer that the deployment resolves server-side (env-var lookup,
- * secrets-manager path, KMS handle, etc.). The plaintext client secret
- * is exchanged with the identity provider inside the deployment's
- * boundary during the code→token exchange in `/v1/auth/callback` and
- * never surfaces on any HTTP response.
+ * A provider carries only REFERENCES to its secrets (`clientSecretRef`,
+ * `spSigningKeyRef`, `spDecryptionKeyRef`): opaque pointers the deployment
+ * resolves server-side (env-var lookup, secrets-manager path, KMS handle,
+ * etc.). The secrets themselves are used inside the deployment's boundary
+ * and never surface on any HTTP response.
  *
- * PKCE is mandatory (S256). Providers that don't support PKCE are
- * rejected at boot; the framework does NOT emit `code_challenge_method`
- * negotiation.
+ * PKCE is mandatory (S256) for the OAuth flows.
  */
 export interface IdentityProviderBinding {
   list(input: IdentityProviderListInput): Promise<IdentityProviderPage>;
   get(input: IdentityProviderGetInput): Promise<ProviderConfig | null>;
   register(input: IdentityProviderRegisterInput): Promise<IdentityProviderRegisterOutcome>;
   unregister(input: IdentityProviderUnregisterInput): Promise<IdentityProviderUnregisterOutcome>;
+  /**
+   * The ways a person can sign in, before anyone is signed in
+   * (`GET /v1/auth/sign-in-options`, unauthenticated). Answer by the email
+   * DOMAIN only, never by whether a person exists:
+   * - with `emailDomain`: the providers whose `domains` include it, from
+   *   the one tenant the domain is verified for (the deployment decides
+   *   how: e.g. the only tenant it serves, or one its operator named);
+   *   none when the domain isn't verified for any tenant;
+   * - without: the route doesn't ask. Sign-in is email first, so nothing
+   *   is offered before an email.
+   * Absent → the route answers an empty list.
+   */
+  readonly signInOptions?: (input: SignInOptionsInput) => Promise<readonly SignInOption[]>;
+  /**
+   * What to give the identity provider so it can send people back
+   * (`signIn`), for a provider registered now or later under this
+   * `providerId`: the same before registration, after it, and after an
+   * unregister and a new registration, so an admin can set up the
+   * identity provider's side first. `undefined` when this deployment
+   * doesn't sign in with that `kind`.
+   * Absent → `GET /v1/auth/providers/:providerId/sign-in` isn't mounted.
+   */
+  readonly signInUrls?: (
+    input: IdentityProviderSignInUrlsInput,
+  ) => Promise<ProviderSignIn | undefined>;
+  /**
+   * Replace a registered provider's configuration, keeping its `signIn`
+   * (the identity provider's side doesn't change). Validated as a new
+   * registration is.
+   * Absent → `PATCH /v1/auth/providers/:providerId` isn't mounted.
+   */
+  readonly update?: (input: IdentityProviderUpdateInput) => Promise<IdentityProviderUpdateOutcome>;
+}
+
+export interface IdentityProviderSignInUrlsInput {
+  readonly tenantId: TenantId;
+  readonly providerId: string;
+  readonly kind: IdentityProviderKind;
+}
+
+export interface IdentityProviderUpdateInput {
+  readonly tenantId: TenantId;
+  /** The whole new configuration (the route merges the changes in). */
+  readonly config: ProviderConfig;
 }
 
-export type IdentityProviderKind = 'oauth2' | 'oidc';
+export type IdentityProviderUpdateOutcome =
+  | { readonly kind: 'ok'; readonly provider: ProviderConfig }
+  | {
+      /** As on registration: 422 `identity-provider-invalid`, with `message`. */
+      readonly kind: 'invalid';
+      readonly message: string;
+    }
+  | { readonly kind: 'not-found' };
 
-export interface ProviderConfig {
-  /** Stable string chosen by the deployment (e.g. `acme-sso`, `globex-oidc`). */
+export interface SignInOptionsInput {
+  /** Lowercase, from the email the person typed. */
+  readonly emailDomain?: string;
+}
+
+/** One way to sign in, as a sign-in page shows it. */
+export interface SignInOption {
+  readonly providerId: string;
+  /** "Sign in with …". */
+  readonly displayName: string;
+  /** Where the browser goes to start signing in with this provider. */
+  readonly signInUrl: string;
+  /**
+   * Whose it is: a workspace's own identity provider (`tenant`), or one
+   * the deployment offers everyone it has added ("Continue with Google",
+   * `deployment`). A sign-in page shows a workspace's own first. Absent:
+   * `tenant`.
+   */
+  readonly owner?: 'tenant' | 'deployment';
+}
+
+/**
+ * - `oidc`: an OpenID Connect identity provider people sign in with
+ *   (Okta, Entra ID, Google, Keycloak…): an `issuer`, the endpoints come
+ *   from its discovery document.
+ * - `saml`: a SAML 2.0 identity provider people sign in with.
+ * - `oauth2`: a plain OAuth 2.0 provider that isn't OpenID Connect (e.g.
+ *   GitHub), with its endpoints given. Pick `oidc` for any provider that
+ *   speaks OpenID Connect.
+ */
+export type IdentityProviderKind = 'oauth2' | 'oidc' | 'saml';
+
+/**
+ * An identity provider's configuration: one shape per `kind`. Narrow on
+ * `kind` before reading kind-specific fields (`clientId`,
+ * `tokenEndpoint`, `idpMetadataXml`…).
+ */
+export type ProviderConfig = OAuth2ProviderConfig | OidcProviderConfig | SamlProviderConfig;
+
+/** What every kind of identity provider has. */
+export interface ProviderConfigBase {
+  /** Stable string chosen by the tenant (e.g. `acme-sso`, `globex-oidc`). */
   readonly providerId: string;
   readonly kind: IdentityProviderKind;
+  /** The name a sign-in page shows ("Sign in with …"). Default: `providerId`. */
+  readonly displayName?: string;
+  /**
+   * The email domains whose people sign in with this provider (lowercase,
+   * e.g. `acme.com`): how an email-first sign-in page finds it.
+   */
+  readonly domains?: readonly string[];
+  /**
+   * Who may sign in the first time: `invite` (default) only people a
+   * tenant admin added; `domain` also anyone from one of `domains`, once
+   * the deployment has verified them.
+   */
+  readonly join?: 'invite' | 'domain';
+  /**
+   * What to give the identity provider so it can send people back: set
+   * by the deployment on what it returns; ignored on registration.
+   */
+  readonly signIn?: ProviderSignIn;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** Where the identity provider sends people back to. */
+export type ProviderSignIn =
+  | {
+      /** OIDC / OAuth 2.0: the redirect URI to allow on the provider's client. */
+      readonly redirectUri: string;
+    }
+  | {
+      /** SAML: the service provider's entity ID, as the IdP knows it. */
+      readonly spEntityId: string;
+      /** SAML: the assertion consumer service URL (HTTP-POST binding). */
+      readonly acsUrl: string;
+      /** SAML: the service provider's metadata, for IdPs that import it. */
+      readonly spMetadataUrl: string;
+    };
+
+/** An OpenID Connect identity provider (sign-in). */
+export interface OidcProviderConfig extends ProviderConfigBase {
+  readonly kind: 'oidc';
+  /** The issuer; its `/.well-known/openid-configuration` gives the endpoints. */
+  readonly issuer: string;
+  readonly clientId: string;
+  /** Opaque pointer resolved server-side. Never a plaintext secret. */
+  readonly clientSecretRef: string;
+  /** Default `openid email profile`. */
+  readonly scopes?: readonly string[];
+  /** From discovery when absent; returned once the deployment has them. */
+  readonly authorizationEndpoint?: string;
+  readonly tokenEndpoint?: string;
+  readonly userinfoEndpoint?: string;
+  readonly jwksEndpoint?: string;
+  readonly allowedRedirectUris?: readonly string[];
+  readonly claimMapping?: ClaimMappingSpec;
+}
+
+/** A SAML 2.0 identity provider (sign-in). */
+export interface SamlProviderConfig extends ProviderConfigBase {
+  readonly kind: 'saml';
+  /** The IdP's metadata XML. Or give `idpEntityId` + `idpSsoUrl` + `idpCertificates`. */
+  readonly idpMetadataXml?: string;
+  readonly idpEntityId?: string;
+  /** The IdP's single sign-on URL (HTTP-Redirect binding). */
+  readonly idpSsoUrl?: string;
+  /** The IdP's signing certificates (PEM); several during a rollover. */
+  readonly idpCertificates?: readonly string[];
+  /**
+   * Opaque pointer to the service provider's signing key (PEM), for IdPs
+   * that require signed AuthnRequests. Never a plaintext key.
+   */
+  readonly spSigningKeyRef?: string;
+  /** Opaque pointer to the key that decrypts encrypted assertions. Never a plaintext key. */
+  readonly spDecryptionKeyRef?: string;
+  /** Require signed assertions. Default `true`. */
+  readonly wantAssertionsSigned?: boolean;
+  /** Assertion attribute names. Defaults: `userId` = the NameID, `email` = `email`. */
+  readonly attributeMapping?: SamlAttributeMapping;
+}
+
+export interface SamlAttributeMapping {
+  readonly userId?: string;
+  readonly email?: string;
+  readonly displayName?: string;
+}
+
+/**
+ * A plain OAuth 2.0 provider that isn't OpenID Connect (e.g. GitHub), run
+ * by this package's own OAuth flow (`/v1/auth/login` + callback, with the
+ * deployment's `exchangeCode`). For a provider that speaks OpenID Connect,
+ * use `oidc`.
+ */
+export interface OAuth2ProviderConfig extends ProviderConfigBase {
+  readonly kind: 'oauth2';
   readonly clientId: string;
   /**
    * Opaque pointer resolved server-side. Never a plaintext secret. The
@@ -69,7 +250,6 @@ export interface ProviderConfig {
    * own `ExchangeCodeFn` MAY honor this field the same way.
    */
   readonly claimMapping?: ClaimMappingSpec;
-  readonly metadata?: Record<string, unknown>;
 }
 
 /**
@@ -140,10 +320,25 @@ export interface IdentityProviderRegisterInput {
   readonly config: ProviderConfig;
 }
 
-export type IdentityProviderRegisterOutcome = {
-  readonly kind: 'ok';
-  readonly providerId: string;
-};
+export type IdentityProviderRegisterOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly providerId: string;
+      /**
+       * The provider as stored: discovered endpoints, `signIn`. Absent from
+       * older bindings; the route then answers with `providerId` alone.
+       */
+      readonly provider?: ProviderConfig;
+    }
+  | {
+      /**
+       * The deployment couldn't use the configuration: the issuer's
+       * discovery failed, the SAML metadata didn't parse, a host it may
+       * not reach. 422 `identity-provider-invalid`, with `message`.
+       */
+      readonly kind: 'invalid';
+      readonly message: string;
+    };
 
 export interface IdentityProviderUnregisterInput {
   readonly tenantId: TenantId;