XMiete Developer Documentation

func handleRequest(w http.ResponseWriter, r *http.Request) {
	validator := auth.NewOidcTokenValidator(
		"https://auth.xmiete.example/.well-known/openid-configuration",
	)
	claims, err := validator.ValidateToken(r.Header.Get("Authorization"), "deposit:create")
	if err != nil {
		if auth.IsInsufficientScopeError(err) {
			http.Error(w, "forbidden", http.StatusForbidden)
		} else {
			http.Error(w, "unauthorized", http.StatusUnauthorized)
		}
		return
	}
	log.Printf("authenticated: sub=%s expires=%s", claims.Subject, claims.ExpiresAt)
	// ... process the request
}

fn validate_bearer_token(header: &str) -> Result<(), AuthError> {
    let validator = OidcTokenValidator::new(
        "https://auth.xmiete.example/.well-known/openid-configuration",
    );
    let claims = validator.validate_token(header, &["deposit:create"])?;
    println!("authenticated: sub={} expires={}", claims.subject, claims.expires_at);
    Ok(())
}

var validator = new OidcTokenValidator(
    "https://auth.xmiete.example/.well-known/openid-configuration"
);

// In production, pass request.getHeader("Authorization").
String incomingAuthHeader = "Bearer <token>";

try {
    TokenClaims claims = validator.validateToken(
        incomingAuthHeader, "deposit:read", "deposit:create"
    );
    System.out.println("Token valid — sub: " + claims.subject()
        + ", scopes: " + claims.scopes());
} catch (OidcTokenValidator.TokenValidationException e) {
    // HTTP 401 — malformed JWT, expired, or wrong issuer
    System.err.println("Token rejected: " + e.getMessage());
    return;
} catch (OidcTokenValidator.InsufficientScopeException e) {
    // HTTP 403 — valid token, scope not granted
    System.err.println("Access denied: " + e.getMessage());
    return;
}

func initiateEIDVerification(ctx context.Context, depositID, tenantEmail string) (string, error) {
	service := eid.NewVerificationService(
		"https://eid-provider.example.com", // e.g., Authada, SkIDentity
		"https://api.xmiete.org/v1",
	)
	session, err := service.InitiateVerification(ctx, eid.VerificationRequest{
		DepositID:   depositID,
		TenantEmail: tenantEmail,
		RedirectURI: "https://yourapp.example.com/eid-callback",
		ClientID:    "xmiete-fintech-client",
	})
	if err != nil {
		return "", fmt.Errorf("eid: initiate session: %w", err)
	}
	// Redirect the tenant's browser to session.AuthorizationURL.
	// The provider POSTs the result to your /webhook/eid endpoint.
	return session.AuthorizationURL, nil
}

async fn initiate_eid_verification(deposit_id: &str, tenant_email: &str) -> String {
    let service = EidVerificationService::new(
        "https://eid-provider.example.com", // e.g., Authada, SkIDentity
        "https://api.xmiete.org/v1",
    );
    let session = service
        .initiate_verification(&VerificationRequest {
            deposit_id:   deposit_id.to_string(),
            tenant_email: tenant_email.to_string(),
            redirect_uri: "https://yourapp.example.com/eid-callback".to_string(),
            client_id:    "xmiete-fintech-client".to_string(),
        })
        .await
        .expect("initiate eID session");
    // Redirect the tenant's browser to session.authorization_url.
    // The provider POSTs the result to your /webhook/eid endpoint.
    session.authorization_url
}

var eidService = new EidVerificationService(
    "https://eid-provider.example",  // e.g., Authada, SkIDentity
    "https://api.xmiete.org/v1"
);

var verificationRequest = new EidVerificationRequest(
    "DEP-123",
    "max.mustermann@example.de",
    "https://app.xmiete.example/eid-callback",
    "xmiete-fintech-client"
);

EidVerificationSession session = eidService
    .initiateVerification(verificationRequest)
    .exceptionally(ex -> new EidVerificationSession(
        "SESSION-STUB-456",
        "https://eid-provider.example/authorize?session_id=SESSION-STUB-456",
        OffsetDateTime.now().plusMinutes(15)
    ))
    .join();

System.out.println("Redirect tenant to: " + session.authorizationUrl());
// The eID provider will POST the result to your /webhook/eid endpoint.

func registerEIDWebhook(service eid.IdentityVerifier, bearerToken, webhookSecret string) {
	handler := eid.NewWebhookHandler(service, bearerToken, func(event eid.WebhookEvent) {
		log.Printf("eID done: deposit=%s status=%s", event.DepositID, event.Status)
	})

	http.HandleFunc("/webhook/eid", func(w http.ResponseWriter, r *http.Request) {
		body, _ := io.ReadAll(r.Body)
		if err := handler.HandleWebhook(body, r.Header.Get("X-Signature"), webhookSecret); err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		w.WriteHeader(http.StatusOK)
	})
}

fn build_webhook_handler(
    service: Arc<dyn EidVerifier>,
    bearer_token: &str,
) -> WebhookHandler {
    WebhookHandler::new(
        service,
        bearer_token.to_string(),
        Some(Box::new(|event| {
            println!("eID done: deposit={} status={:?}", event.deposit_id, event.status);
        })),
    )
}
// In your Axum / Actix handler:
//   let sig = headers["X-Signature"].to_str().unwrap_or("");
//   handler.handle_webhook(&body, sig, &webhook_secret).await?;

String webhookSecret = System.getenv().getOrDefault("EID_WEBHOOK_SECRET", "dev-secret-only");

var webhookHandler = new EidWebhookHandler(
    eidService,
    "Bearer <xmiete-service-token>",
    event -> System.out.println("eID done — status: " + event.status()
        + ", providerRef: " + event.providerReference())
);

// In your servlet / Spring @PostMapping:
//   byte[] body = request.getInputStream().readAllBytes();
//   String sig  = request.getHeader("X-Signature");
//   webhookHandler.handleWebhook(body, sig, webhookSecret);

func requestWalletPresentation(ctx context.Context, depositID, responseURI string) error {
	verifier := openid4vp.NewVpVerifierService(
		"https://verifier.yourapp.example.com",
		"https://auth.example.com/.well-known/jwks.json",
	)

	// Step 1 — build the VP request and deliver it to the wallet (QR or deep-link).
	result, err := verifier.BuildVpRequest(ctx, depositID, responseURI)
	if err != nil {
		return fmt.Errorf("openid4vp: build request: %w", err)
	}
	// Persist result.Nonce in your session store — required for step 3.
	// Serialize result.VpRequest as JSON and embed in QR code or deep-link.

	// Step 3 — wallet POSTs vp_token to responseURI; verify it here.
	claims, err := verifier.VerifyVpToken(ctx, "<vp_token from wallet>", result.Nonce, responseURI)
	if err != nil {
		return fmt.Errorf("openid4vp: invalid presentation: %w", err)
	}
	log.Printf("verified: deposit=%s pledged=%s bank=%s",
		claims.DepositID, claims.PledgeDate, claims.IssuingBank)
	return nil
}

async fn request_wallet_presentation(
    deposit_id: &str,
    response_uri: &str,
) -> Result<(), VpError> {
    let verifier = VpVerifierService::new(
        "https://verifier.yourapp.example.com".to_string(),
        "https://auth.example.com/.well-known/jwks.json".to_string(),
    );

    // Step 1 — build the VP request; deliver it to the wallet via QR or deep-link.
    let (nonce, _vp_request) = verifier.build_vp_request(deposit_id, response_uri).await?;
    // Persist nonce in your session store — required for step 3.
    // Serialize _vp_request as JSON and embed in QR code or deep-link.

    // Step 3 — wallet POSTs vp_token to response_uri; verify it here.
    let claims = verifier
        .verify_vp_token("<vp_token from wallet>", &nonce, response_uri)
        .await?;
    println!(
        "verified: deposit={} pledged={} bank={}",
        claims.deposit_id, claims.pledge_date, claims.issuing_bank
    );
    Ok(())
}

var vpVerifier = new OpenId4VpService(
    "https://verifier.yourapp.example.com",
    "https://auth.example.com/.well-known/jwks.json"
);

// Step 1 — build a VP request and deliver it to the wallet (QR or deep-link).
String responseUri = "https://yourapp.example.com/vp-response";
VpRequestResult req = vpVerifier.buildVpRequest("DEP-123", responseUri).join();
String nonce = req.nonce();
// Persist nonce; serialize req.vpRequest() as JSON and embed in QR code.

// Step 3 — wallet POSTs vp_token to responseUri; verify it here.
VerifiedClaims vp = vpVerifier.verifyVpToken("<vp_token>", nonce, responseUri).join();
System.out.println("Deposit: " + vp.depositId());
System.out.println("Pledge date: " + vp.pledgeDate());
System.out.println("Issuing bank: " + vp.issuingBank());

func handleAuthError(w http.ResponseWriter, err error) {
	switch {
	case auth.IsInsufficientScopeError(err):
		// HTTP 403 — valid token, but the required scope is not granted
		http.Error(w, "insufficient scope", http.StatusForbidden)
	case auth.IsTokenValidationError(err):
		// HTTP 401 — malformed JWT, expired, or wrong issuer
		http.Error(w, "unauthorized", http.StatusUnauthorized)
	default:
		http.Error(w, "internal error", http.StatusInternalServerError)
	}
}

fn http_status_for_auth_error(err: &AuthError) -> u16 {
    match err {
        AuthError::TokenExpired | AuthError::MalformedJwt(_) => 401,
        AuthError::InsufficientScope { .. }                   => 403,
        AuthError::UnexpectedIssuer(_)                        => 401,
        _                                                     => 500,
    }
}

fn log_vp_error(err: &VpError) {
    match err {
        VpError::NonceMismatch  => eprintln!("replay attack: nonce mismatch"),
        VpError::StaleKbJwt     => eprintln!("presentation expired (>5 min old)"),
        VpError::AudMismatch    => eprintln!("response_uri mismatch"),
        other                   => eprintln!("VP verification failed: {other}"),
    }
}

// Java uses checked exceptions — see Authentication section above.