001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.client.mcp.auth;
018
019import java.net.*;
020import java.util.*;
021
022/**
023 * SEP-2352 optional persistence SPI for Dynamic-Client-Registration / pre-registered credentials, keyed by the
024 * authorization server's {@code issuer} identifier.
025 *
026 * <p>
027 * Persistence is <b>SHOULD-level</b>: an MCP client that performs on-demand DCR on every connection
028 * with <i>no</i> store is fully compliant.  When a store <i>is</i> used, the SEP-2352 keying MUST bites &mdash;
029 * credentials MUST be associated with the specific AS that issued them, and separate registration state MUST be kept per
030 * AS ({@link InMemoryMcpClientRegistrationStore} keys by {@code issuer.toString()}).  {@link McpClientRegistrationManager}
031 * consults a store (if present) to reuse an issuer-keyed entry and to drive re-registration on AS migration.
032 *
033 * <h5 class='topic'>Security</h5>
034 * <p>
035 * A store holds {@code clientSecret} / registration-access-token material (via {@link McpClientRegistration}).  The
036 * default {@link InMemoryMcpClientRegistrationStore} is process-scoped; a durable implementation a caller supplies is
037 * responsible for at-rest protection and MUST NOT log credential material.
038 *
039 * @since 10.0.0
040 */
041public interface McpClientRegistrationStore {
042
043   /**
044    * Returns the registration stored for the given AS issuer, if any.
045    *
046    * @param issuer The authorization server {@code issuer} identifier.  Must not be <jk>null</jk>.
047    * @return The stored registration, or {@link Optional#empty()} if none is stored for that issuer.
048    */
049   Optional<McpClientRegistration> find(URI issuer);
050
051   /**
052    * Stores (or replaces) the registration for the given AS issuer.
053    *
054    * @param issuer The authorization server {@code issuer} identifier.  Must not be <jk>null</jk>.
055    * @param registration The registration to store.  Must not be <jk>null</jk>.
056    */
057   void put(URI issuer, McpClientRegistration registration);
058
059   /**
060    * Removes any registration stored for the given AS issuer.
061    *
062    * @param issuer The authorization server {@code issuer} identifier.  Must not be <jk>null</jk>.
063    */
064   void remove(URI issuer);
065}