{
  "openapi": "3.1.0",
  "info": {
    "title": "Yunfu enterprise MFA and SSO",
    "version": "1.0.0",
    "description": "Implemented local Cookie-session OIDC integration. SQLite/D1 adapter only. No SCIM, native SAML, local MFA enrollment or OAuth machine-to-machine management grant. See ENTERPRISE-MFA-SSO-INTEGRATION.md for constraints and rollout requirements."
  },
  "servers": [
    {
      "url": "https://service.example.com",
      "description": "Replace with configured login origin"
    }
  ],
  "security": [
    {
      "consoleSession": []
    },
    {
      "adminSession": []
    }
  ],
  "paths": {
    "/api/identity-hub/policy": {
      "get": {
        "summary": "Read tenant policy (platform admin or tenant team admin)",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tenantId": {
                      "type": "string"
                    },
                    "revision": {
                      "type": "integer"
                    },
                    "policy": {
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/Policy"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "connection": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Public issuer, clientId, redirectUri and clientAuth; never client secret."
                    },
                    "availability": {
                      "type": "object",
                      "properties": {
                        "available": {
                          "type": "boolean"
                        },
                        "unavailableReason": {
                          "type": "string"
                        }
                      },
                      "required": []
                    },
                    "protocols": {
                      "type": "object"
                    },
                    "routes": {
                      "type": "object"
                    }
                  },
                  "required": []
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Session required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized or MFA/step-up required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not registered or found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Version, account, binding or authorization changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Database adapter not supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "tenantId",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Required for platform admin; tenant admin can only select own tenant."
          }
        ]
      },
      "post": {
        "summary": "Platform admin only: CAS update with current password",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tenantId": {
                      "type": "string"
                    },
                    "revision": {
                      "type": "integer"
                    },
                    "policy": {
                      "$ref": "#/components/schemas/Policy"
                    }
                  },
                  "required": [
                    "tenantId",
                    "revision",
                    "policy"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Session required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized or MFA/step-up required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not registered or found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Version, account, binding or authorization changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Database adapter not supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PolicyChange"
              }
            }
          }
        }
      }
    },
    "/api/identity-hub/bindings": {
      "get": {
        "summary": "List own tenant eligible personal identities; max 500",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tenantId": {
                      "type": "string"
                    },
                    "issuer": {
                      "type": "string"
                    },
                    "accounts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "accountId": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "login": {
                            "type": "string"
                          },
                          "role": {
                            "enum": [
                              "tenant_admin",
                              "agent",
                              "finance"
                            ]
                          },
                          "subject": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": []
                      }
                    },
                    "bindings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "accountId": {
                            "type": "string"
                          },
                          "subject": {
                            "type": "string"
                          },
                          "created": {
                            "type": "integer"
                          }
                        },
                        "required": []
                      }
                    },
                    "truncated": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "tenantId",
                    "issuer",
                    "accounts",
                    "bindings",
                    "truncated"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Session required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized or MFA/step-up required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not registered or found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Version, account, binding or authorization changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Database adapter not supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "tenantId",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Required for platform admin; tenant admin can only select own tenant."
          }
        ]
      },
      "post": {
        "summary": "Explicit bind/unbind with current password and expectedSubject",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BindingResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Session required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized or MFA/step-up required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not registered or found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Version, account, binding or authorization changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Database adapter not supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BindingChange"
              }
            }
          }
        },
        "description": "Tenant team admins need fresh MFA when required. Platform admin personal-session recovery is a documented current-password plus audit exception, not proof of tenant MFA. Never accepts caller issuer."
      }
    },
    "/api/identity-hub/assurance": {
      "get": {
        "summary": "Read authentication gates only; business permissions still apply",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Assurance"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Session required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized or MFA/step-up required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not registered or found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Version, account, binding or authorization changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Database adapter not supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/identity-hub/resolve": {
      "post": {
        "summary": "Resolve registered enterprise identifier; same-origin only",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "identifier": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "name",
                    "identifier"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Session required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized or MFA/step-up required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not registered or found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Version, account, binding or authorization changed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Database adapter not supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "identifier": {
                    "type": "string"
                  }
                },
                "required": [
                  "identifier"
                ]
              }
            }
          }
        },
        "security": []
      }
    },
    "/api/identity-hub/login": {
      "get": {
        "summary": "Start OIDC browser redirect with transaction Cookie",
        "security": [],
        "parameters": [
          {
            "name": "enterprise",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Use registered enterprise identifier when MFA is configured."
          },
          {
            "name": "reauth",
            "in": "query",
            "schema": {
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "sessionSlot",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{32}$"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to trusted issuer; HttpOnly transaction Cookie."
          },
          "400": {
            "description": "Invalid request; HTML failure"
          },
          "403": {
            "description": "Disabled/unavailable enterprise; HTML failure"
          },
          "503": {
            "description": "OIDC unavailable; HTML failure"
          }
        }
      }
    },
    "/api/identity-hub/callback": {
      "get": {
        "summary": "OIDC callback; state plus browser-bound transaction Cookie required",
        "security": [],
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML session handoff; server sets HttpOnly local session Cookie."
          },
          "400": {
            "description": "Invalid OIDC transaction or protocol; no business session"
          },
          "403": {
            "description": "Binding, account or MFA denied; no business session"
          },
          "409": {
            "description": "Authentication policy changed during login; start again"
          },
          "503": {
            "description": "Identity provider unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "consoleSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "yunfu_session",
        "description": "Existing console session; portal-scoped/session-slot cookies also supported by existing authentication."
      },
      "adminSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "yunfu_admin_session"
      }
    },
    "schemas": {
      "Policy": {
        "type": "object",
        "properties": {
          "mode": {
            "enum": [
              "optional",
              "required"
            ]
          },
          "acrValues": {
            "type": "array",
            "minItems": 1,
            "maxItems": 12,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          "amrAll": {
            "type": "array",
            "maxItems": 12,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          "maxAgeSeconds": {
            "type": "integer",
            "minimum": 300,
            "maximum": 28800
          },
          "highRiskMaxAgeSeconds": {
            "type": "integer",
            "minimum": 60,
            "maximum": 300,
            "description": "Also <= maxAgeSeconds"
          }
        },
        "required": [
          "mode",
          "acrValues",
          "amrAll",
          "maxAgeSeconds",
          "highRiskMaxAgeSeconds"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "MFA_REQUIRED",
              "STEP_UP_REQUIRED",
              "MFA_UNAVAILABLE"
            ]
          },
          "loginUrl": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "PolicyChange": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "maxLength": 100
          },
          "revision": {
            "type": "integer",
            "minimum": 0
          },
          "currentPassword": {
            "type": "string",
            "writeOnly": true
          },
          "policy": {
            "$ref": "#/components/schemas/Policy"
          }
        },
        "required": [
          "tenantId",
          "revision",
          "currentPassword",
          "policy"
        ]
      },
      "BindingChange": {
        "type": "object",
        "properties": {
          "action": {
            "enum": [
              "bind",
              "unbind"
            ]
          },
          "tenantId": {
            "type": "string",
            "description": "Required for platform admin; tenant admin may omit own tenant."
          },
          "accountId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "subject": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "expectedSubject": {
            "type": [
              "string",
              "null"
            ]
          },
          "currentPassword": {
            "type": "string",
            "writeOnly": true
          }
        },
        "required": [
          "action",
          "accountId",
          "subject",
          "expectedSubject",
          "currentPassword"
        ]
      },
      "BindingResult": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "tenantId": {
            "type": "string"
          },
          "accountId": {
            "type": "string"
          },
          "subject": {
            "type": [
              "string",
              "null"
            ]
          },
          "changed": {
            "type": "boolean"
          },
          "sessionsRevoked": {
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "tenantId",
          "accountId",
          "subject",
          "changed",
          "sessionsRevoked"
        ]
      },
      "Assurance": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string"
          },
          "required": {
            "type": "boolean"
          },
          "policyRevision": {
            "type": "integer"
          },
          "authenticatedAt": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Seconds since epoch; historical proof time, not proof that present policy passes."
          },
          "method": {
            "enum": [
              "local",
              "oidc"
            ]
          },
          "access": {
            "type": "object",
            "properties": {
              "read": {
                "type": "boolean"
              },
              "write": {
                "type": "boolean"
              }
            },
            "required": [
              "read",
              "write"
            ]
          },
          "loginUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "expiresAt": {
            "type": "integer",
            "description": "Milliseconds since epoch"
          },
          "automaticFallback": {
            "const": false
          }
        },
        "required": [
          "tenantId",
          "required",
          "policyRevision",
          "authenticatedAt",
          "method",
          "access",
          "loginUrl",
          "expiresAt",
          "automaticFallback"
        ]
      }
    }
  }
}