Add support for only-return-existing flag

acme4j-client/src/main/java/org/shredzone/acme4j/AccountBuilder.java

@@ -41,6 +41,7 @@ public class AccountBuilder {
 
     private List<URI> contacts = new ArrayList<>();
     private Boolean termsOfServiceAgreed;
+    private Boolean onlyExisting;
     private String keyIdentifier;
 
     /**
@@ -81,6 +82,18 @@ public class AccountBuilder {
         return this;
     }
 
+    /**
+     * Signals that only an existing account should be returned. The server will not
+     * create a new account if the key is not known. This is useful if you only have your
+     * account's key pair available, but not your account's location URL.
+     *
+     * @return itself
+     */
+    public AccountBuilder onlyExisting() {
+        this.onlyExisting = true;
+        return this;
+    }
+
     /**
      * Sets a Key Identifier provided by the CA. Use this if your CA requires an
      * individual account identification, e.g. your customer number.
@@ -125,6 +138,9 @@ public class AccountBuilder {
                 claims.put("external-account-binding",
                         createExternalAccountBinding(keyIdentifier, session.getKeyPair(), resourceUrl));
             }
+            if (onlyExisting != null) {
+                claims.put("only-return-existing", onlyExisting);
+            }
 
             conn.sendSignedRequest(resourceUrl, claims, session, true);
             conn.accept(HttpURLConnection.HTTP_OK, HttpURLConnection.HTTP_CREATED);

acme4j-client/src/test/java/org/shredzone/acme4j/AccountBuilderTest.java

@@ -191,4 +191,49 @@ public class AccountBuilderTest {
         provider.close();
     }
 
+    /**
+     * Test if an existing account is properly returned.
+     */
+    @Test
+    public void testOnlyExistingRegistration() throws Exception {
+        TestableConnectionProvider provider = new TestableConnectionProvider() {
+            @Override
+            public void sendSignedRequest(URL url, JSONBuilder claims, Session session, boolean enforceJwk) {
+                assertThat(session, is(notNullValue()));
+                assertThat(url, is(resourceUrl));
+                assertThat(claims.toString(), sameJSONAs(getJSON("newAccountOnlyExisting").toString()));
+                assertThat(enforceJwk, is(true));
+            }
+
+            @Override
+            public int accept(int... httpStatus) throws AcmeException {
+                assertThat(httpStatus, isIntArrayContainingInAnyOrder(HttpURLConnection.HTTP_OK, HttpURLConnection.HTTP_CREATED));
+                return HttpURLConnection.HTTP_OK;
+            }
+
+            @Override
+            public URL getLocation() {
+                return locationUrl;
+            }
+
+            @Override
+            public JSON readJsonResponse() {
+                return getJSON("newAccountResponse");
+            }
+        };
+
+        provider.putTestResource(Resource.NEW_ACCOUNT, resourceUrl);
+
+        AccountBuilder builder = new AccountBuilder();
+        builder.onlyExisting();
+
+        Session session = provider.createSession();
+        Account account = builder.create(session);
+
+        assertThat(account.getLocation(), is(locationUrl));
+        assertThat(session.getKeyIdentifier(), is(locationUrl.toString()));
+
+        provider.close();
+    }
+
 }

acme4j-client/src/test/resources/json/newAccountOnlyExisting.json

@@ -0,0 +1,3 @@
+{
+  "only-return-existing": true
+}

src/site/markdown/usage/register.md

@@ -14,6 +14,17 @@ Account account = builder.create(session);
 URL accountLocationUrl = account.getLocation();
 ```
 
+## Find out your account's location URL
+
+You can also use the `AccountBuilder` to find out the location URL of your existing account:
+
+```java
+Account account = new AccountBuilder().onlyExisting().create(session);
+URL accountLocationUrl = account.getLocation();
+```
+
+If you do not have an account yet, an exception is raised instead, and no new account is created.
+
 ## Update your Account
 
 At some point, you may want to update your account. For example your contact address might have changed. To do so, invoke `Account.modify()`, perform the changes, and invoke `commit()` to make them permanent.