work in progress

This commit is contained in:
2026-08-16 22:00:08 +02:00
parent a914ef1ec4
commit 3c11a88a33
60 changed files with 4487 additions and 41 deletions
+16 -2
View File
@@ -129,6 +129,18 @@ suspended), the message is buffered briefly. Buffer lifetime is short (seconds);
if the extension does not reconnect within that window the message is discarded
and the run must be restarted.
**`POST /run/relay/:runId/confirm` (extension only)** and
**`GET /run/relay/:runId/confirm` (polled — companion only)**
PIN confirmation handshake (`../interfaces.md`, "PIN confirmation"). The
extension POSTs when its user clicks Confirm; the companion polls the GET
until it sees `{ confirmed: true }` before proceeding to select/send a
credential. Current scope: a plain in-memory marker in
`RelaySessionRegistry` (same component as the relay message buffer above,
not a separate store), pruned on its own longer TTL — see that class's
Javadoc. Both requests are unauthenticated, same as the rest of this
surface at current scope; `runId` itself is the only addressing key, same
trust model as the relay endpoints above.
### Admin / website endpoints
Domain registration and account management. Deferred beyond the one endpoint
@@ -160,8 +172,10 @@ completing Phase 1. The server maintains a mapping of run ID → active connecti
**Message flow:**
1. Extension opens WS for run ID (after Phase 1).
2. Companion POSTs kem_ciphertext → server pushes to extension WS (Phase 2).
3. Companion POSTs encrypted credential → server pushes to extension WS (Phase 4).
4. WS closes on run end (delivered, error, or TTL expiry).
3. Extension user clicks Confirm → extension POSTs `/run/relay/:runId/confirm`;
companion polls the same path (GET) and unblocks once it sees confirmed.
4. Companion POSTs encrypted credential → server pushes to extension WS (Phase 4).
5. WS closes on run end (delivered, error, or TTL expiry).
The extension is responsible for keeping its WS connection alive across service
worker suspensions using `chrome.alarms` or equivalent. The server-side buffer
@@ -0,0 +1,39 @@
package dev.locqr.server.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* {@code host_permissions} in the extension's manifest only changes
* browser-side behavior — it lets the service worker's fetch() read a
* response that's missing CORS headers. It does not stop the browser from
* sending {@code Origin: chrome-extension://<id>} on that fetch, and it has
* no effect at all on whether *this server* enforces its own CORS policy
* against that origin. Found this the hard way: scoping this mapping to
* {@code /**} initially blocked the extension's own {@code /security/report}
* calls with a 403 — Spring's CORS check doesn't know or care about
* host_permissions, it just saw an Origin not in the allowlist. The
* extension needed *no* CORS config at all (that's what host_permissions is
* for); only a real webpage does. So this stays scoped to exactly the one
* endpoint a webpage calls directly in this slice — not the whole API —
* specifically so it can never again regress an extension-only endpoint by
* accident the way the blanket {@code /**} mapping just did.
*/
@Configuration
public class CorsConfig implements WebMvcConfigurer {
private final LocqrProperties properties;
public CorsConfig(LocqrProperties properties) {
this.properties = properties;
}
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/domain/registration")
.allowedOrigins(properties.allowedOrigins().toArray(new String[0]))
.allowedMethods("GET")
.allowedHeaders("*");
}
}
@@ -2,6 +2,8 @@ package dev.locqr.server.config;
import org.springframework.boot.context.properties.ConfigurationProperties;
import java.util.List;
/**
* Binds the {@code locqr.*} tree in application.yml. Current (PoC) scope
* config only — see server/claude.md for the current-vs-production split.
@@ -11,6 +13,7 @@ public record LocqrProperties(
String testDomain,
String ed25519SecretKeyPath,
String registrationCertPath,
List<String> allowedOrigins,
Run run,
Relay relay
) {
@@ -0,0 +1,39 @@
package dev.locqr.server.controller;
import dev.locqr.server.dto.PinConfirmationResponse;
import dev.locqr.server.relay.RelaySessionRegistry;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* PIN-confirmation handshake (interfaces.md, "PIN confirmation") — the
* extension posts here when its user clicks Confirm; the companion polls
* here after its own local pin_display gate before it's allowed to proceed
* to credential_select. Neither side trusts the other's timing without
* this: the companion no longer just proceeds on its own schedule
* (mobile/claude.md, updated).
*/
@RestController
public class PinConfirmationController {
private final RelaySessionRegistry registry;
public PinConfirmationController(RelaySessionRegistry registry) {
this.registry = registry;
}
@PostMapping("/run/relay/{runId}/confirm")
public ResponseEntity<Void> confirm(@PathVariable String runId) {
registry.confirmPin(runId);
return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
}
@GetMapping("/run/relay/{runId}/confirm")
public PinConfirmationResponse status(@PathVariable String runId) {
return new PinConfirmationResponse(registry.isPinConfirmed(runId));
}
}
@@ -0,0 +1,8 @@
package dev.locqr.server.dto;
import com.fasterxml.jackson.annotation.JsonProperty;
/** GET /run/relay/:runId/confirm response — interfaces.md "PIN confirmation". */
public record PinConfirmationResponse(
@JsonProperty("confirmed") boolean confirmed
) {}
@@ -26,6 +26,13 @@ import java.util.concurrent.TimeUnit;
* bounds how long, matching the doc's "buffer lifetime is short (seconds);
* if the extension does not reconnect within that window the message is
* discarded and the run must be restarted."
*
* <p>Also tracks the PIN-confirmation handshake (interfaces.md, "PIN
* confirmation"): the extension posts a confirmation here when its user
* clicks Confirm, and the companion polls for it before it's allowed to
* proceed past its own local pin_display gate. Same ephemeral-state
* lifecycle and TTL as the message buffer above, so it's tracked alongside
* it rather than in a separate component.
*/
@Component
public class RelaySessionRegistry {
@@ -34,8 +41,17 @@ public class RelaySessionRegistry {
private record Buffered(String json, Instant receivedAt) {}
// Not a functional deadline — the extension's own pin_ttl alarm is what
// actually bounds how long a user has to confirm. This is just memory
// hygiene for the server, so it's set generously longer than any
// realistic pin_ttl rather than reusing the much shorter relay message
// buffer TTL (8s — nowhere near enough time for a human to compare a
// PIN and click Confirm).
private static final Duration CONFIRMATION_TTL = Duration.ofMinutes(10);
private final Map<String, WebSocketSession> sessions = new ConcurrentHashMap<>();
private final Map<String, Queue<Buffered>> buffers = new ConcurrentHashMap<>();
private final Map<String, Instant> confirmedAt = new ConcurrentHashMap<>();
private final Duration bufferTtl;
private final ScheduledExecutorService cleanup = Executors.newSingleThreadScheduledExecutor(r -> {
Thread t = new Thread(r, "relay-buffer-cleanup");
@@ -45,7 +61,7 @@ public class RelaySessionRegistry {
public RelaySessionRegistry(LocqrProperties properties) {
this.bufferTtl = Duration.ofSeconds(properties.relay().bufferTtlSeconds());
this.cleanup.scheduleAtFixedRate(this::pruneExpiredBuffers, 1, 1, TimeUnit.SECONDS);
this.cleanup.scheduleAtFixedRate(this::pruneExpired, 1, 1, TimeUnit.SECONDS);
}
public void register(String runId, WebSocketSession session) {
@@ -57,6 +73,16 @@ public class RelaySessionRegistry {
sessions.remove(runId, session);
}
/** Extension side: user clicked Confirm. */
public void confirmPin(String runId) {
confirmedAt.put(runId, Instant.now());
}
/** Companion side: has the extension confirmed yet? */
public boolean isPinConfirmed(String runId) {
return confirmedAt.containsKey(runId);
}
/**
* Forwards a relay message to the extension's socket if open; otherwise
* buffers it for {@link #bufferTtl}.
@@ -86,14 +112,16 @@ public class RelaySessionRegistry {
}
}
private void pruneExpiredBuffers() {
Instant cutoff = Instant.now().minus(bufferTtl);
private void pruneExpired() {
Instant bufferCutoff = Instant.now().minus(bufferTtl);
buffers.forEach((runId, queue) -> {
queue.removeIf(m -> m.receivedAt().isBefore(cutoff));
queue.removeIf(m -> m.receivedAt().isBefore(bufferCutoff));
if (queue.isEmpty()) {
buffers.remove(runId, queue);
}
});
Instant confirmationCutoff = Instant.now().minus(CONFIRMATION_TTL);
confirmedAt.entrySet().removeIf(e -> e.getValue().isBefore(confirmationCutoff));
}
private void send(WebSocketSession session, String json) {
+15
View File
@@ -1,10 +1,25 @@
server:
port: ${API_PORT:3000}
ssl:
bundle: api-locqr-dev
spring:
ssl:
bundle:
pem:
api-locqr-dev:
keystore:
certificate: ${API_TLS_CERT_PATH:file:../dev/certs/api.locqr.dev.pem}
private-key: ${API_TLS_KEY_PATH:file:../dev/certs/api.locqr.dev-key.pem}
locqr:
test-domain: ${TEST_DOMAIN:test.locqr.dev}
ed25519-secret-key-path: ${ED25519_SECRET_KEY_PATH:../dev/keys/ed25519-secret.b64}
registration-cert-path: ${REGISTRATION_CERT_PATH:../dev/certs/test-registration.b64}
# Webpage-context clients only (test website, later the companion web
# stub) — the extension's service worker bypasses CORS via manifest
# host_permissions instead. Ports match dev.md's documented defaults.
allowed-origins: ${ALLOWED_ORIGINS:https://test.locqr.dev:5173,https://test.locqr.dev:5174}
run:
qr-ttl-seconds: 90
max-auto-refresh: 3
@@ -55,6 +55,11 @@ class RunFlowIntegrationTest {
@DynamicPropertySource
static void dynamicKeyAndCert(DynamicPropertyRegistry registry) throws Exception {
// TLS termination (server.ssl.*, application.yml) is verified separately against
// the real mkcert-issued cert and trust chain — see dev.md / server/claude.md.
// These tests are about the API contract, so they talk plain HTTP to a random port.
registry.add("server.ssl.enabled", () -> false);
Path tempDir = Files.createTempDirectory("locqr-server-it");
TestEd25519Keys.Generated keys = TestEd25519Keys.generate();
@@ -228,6 +233,45 @@ class RunFlowIntegrationTest {
.expectStatus().isBadRequest();
}
// --- PIN confirmation handshake (interfaces.md) ---
@Test
void pinConfirmation_isFalseUntilTheExtensionConfirms_thenTrue() {
String runId = "confirm-it-" + UUID.randomUUID();
client.get().uri("/run/relay/{runId}/confirm", runId)
.exchange()
.expectStatus().isOk()
.expectBody(PinConfirmationResponse.class)
.isEqualTo(new PinConfirmationResponse(false));
client.post().uri("/run/relay/{runId}/confirm", runId)
.exchange()
.expectStatus().isNoContent();
client.get().uri("/run/relay/{runId}/confirm", runId)
.exchange()
.expectStatus().isOk()
.expectBody(PinConfirmationResponse.class)
.isEqualTo(new PinConfirmationResponse(true));
}
@Test
void pinConfirmation_doesNotConfirmADifferentRunId() {
String confirmedRunId = "confirm-it-" + UUID.randomUUID();
String otherRunId = "confirm-it-" + UUID.randomUUID();
client.post().uri("/run/relay/{runId}/confirm", confirmedRunId)
.exchange()
.expectStatus().isNoContent();
client.get().uri("/run/relay/{runId}/confirm", otherRunId)
.exchange()
.expectStatus().isOk()
.expectBody(PinConfirmationResponse.class)
.isEqualTo(new PinConfirmationResponse(false));
}
private static String randomBase64(int numBytes) {
byte[] bytes = new byte[numBytes];
new java.security.SecureRandom().nextBytes(bytes);
@@ -90,6 +90,7 @@ class SigningServiceTest {
"test.locqr.dev",
keyFile.toString(),
"/nonexistent",
java.util.List.of(),
new LocqrProperties.Run(90, 3, 120),
new LocqrProperties.Relay(8));
}
@@ -9,6 +9,8 @@ import org.springframework.web.socket.WebSocketSession;
import java.util.ArrayList;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.never;
@@ -100,9 +102,34 @@ class RelaySessionRegistryTest {
verify(session, never()).sendMessage(any());
}
@Test
void isPinConfirmed_isFalse_forARunThatHasNotBeenConfirmed() {
RelaySessionRegistry registry = registry(30);
assertFalse(registry.isPinConfirmed("run-1"));
}
@Test
void isPinConfirmed_isTrue_afterConfirmPin() {
RelaySessionRegistry registry = registry(30);
registry.confirmPin("run-1");
assertTrue(registry.isPinConfirmed("run-1"));
}
@Test
void confirmPin_doesNotConfirmADifferentRunId() {
RelaySessionRegistry registry = registry(30);
registry.confirmPin("run-1");
assertFalse(registry.isPinConfirmed("run-other"));
}
private RelaySessionRegistry registry(int bufferTtlSeconds) {
RelaySessionRegistry registry = new RelaySessionRegistry(new LocqrProperties(
"test.locqr.dev", "unused", "unused",
"test.locqr.dev", "unused", "unused", java.util.List.of(),
new LocqrProperties.Run(90, 3, 120),
new LocqrProperties.Relay(bufferTtlSeconds)));
created.add(registry);
@@ -46,6 +46,7 @@ class RegistrationCertificateStoreTest {
TEST_DOMAIN,
"unused",
certPath,
java.util.List.of(),
new LocqrProperties.Run(90, 3, 120),
new LocqrProperties.Relay(8));
}