@catheadowl/ukp 0.1.0 → 0.2.0

package/src/commands/serve.ts

@@ -7,6 +7,7 @@ import {
   type KitParsed,
   type UkpCommandSpec,
 } from "./kit.ts";
+import { normalizeTlsSanEntry } from "../capabilities/tls-identity.ts";
 import { DISCOVERY_PATH, startUkpServer, type ServeInfo } from "../server.ts";
 
 export interface ServeCommandContext {
@@ -36,15 +37,18 @@ export const SERVE_SPEC: UkpCommandSpec = {
   group: "operations",
   description:
     "Expose a registered endpoint over HTTP using the ukp-remote wire, or — without --endpoint — serve every local endpoint as one host door routed by name.",
-  usage: "[--endpoint <name>] [--host <addr>] [--port <n>] [--tls | --tls-cert <pem> --tls-key <pem>]",
+  usage: "[--endpoint <name>] [--host <addr>] [--port <n>] [--tls [--tls-san <ip|dns>]… | --tls-cert <pem> --tls-key <pem>] [--max-idle <seconds>] [--systemd-socket]",
   options: [
     { flags: "--endpoint <name>", help: "the registered endpoint to expose; omit it to serve the whole registry as a host door (/e/<name>/ routing, all endpoints, one port)" },
     { flags: "--host <addr>", help: "listen address (default 127.0.0.1, loopback only without a token)" },
     { flags: "--port <n>", help: "listen port (default 8570)" },
     { flags: "--tls", help: "serve HTTPS with a self-signed identity (auto-generated under .ukp/tls/, SAN covers this host's addresses; clients pin it at registration)" },
+    { flags: "--tls-san <ip|dns>", help: "extra SAN entry for the --tls self-signed identity (repeatable): a public/NAT IP or hostname no NIC of this host carries; a persisted certificate missing an entry is re-signed over the same key (pin unchanged, pinned clients re-anchor)", multi: true },
     { flags: "--tls-cert <pem>", help: "TLS certificate (chain) PEM path — Let's Encrypt, mkcert, or a private CA; pair with --tls-key" },
     { flags: "--tls-key <pem>", help: "TLS private key PEM path; pair with --tls-cert" },
     { flags: "--allow-anonymous", help: "permit tokenless access on loopback (local testing, or an ssh-forwarded host door where SSH carries encryption and auth; reverse-proxy deployments still require UKP_SERVE_TOKEN)" },
+    { flags: "--max-idle <seconds>", help: "exit after <seconds> without requests (self-reap; the orphan backstop for on-demand-woken doors — fractional values accepted for tests)" },
+    { flags: "--systemd-socket", help: "serve on the systemd socket-activation listener (LISTEN_FDS fd 3) instead of binding a port — the port belongs to your .socket unit; Linux-only" },
   ],
   helpSuffix: [
     "",
@@ -56,14 +60,14 @@ export const SERVE_SPEC: UkpCommandSpec = {
     "  GET  /v1/nav?path=&depth=    markdown route view (ukp.nav.v1)",
     "  GET  /v1/rg?query=…          lexical search (ukp.rg.v1, ukp_uri handoff)",
     "",
-    "Wire (ukp-remote v1), host door (no --endpoint; ADR-REM-004):",
+    "Wire (ukp-remote v1), host door (no --endpoint):",
     `  GET  ${DISCOVERY_PATH}        door document (scope:"host", endpoint roster)`,
     "  GET  /e/<name>/.well-known/ukp.json   per-endpoint document (same shape",
     "                                as single-endpoint mode; TOFU pins anchor here)",
     "  POST /e/<name>/v1/search     capabilities routed by endpoint name",
     "  GET  /e/<name>/v1/read|nav|rg",
     "",
-    "Auth (deny by default, RQ-18):",
+    "Auth (deny by default):",
     "  Serving requires UKP_SERVE_TOKEN (comma-separate several: alice,bob;",
     "  any listed token authorizes). Tokenless serving is an explicit opt-in:",
     "  --allow-anonymous, loopback binds only. The discovery document stays",
@@ -85,6 +89,12 @@ export const SERVE_SPEC: UkpCommandSpec = {
     "  2026-01 —, mkcert, a private CA). Plain HTTP remains loopback-only by",
     "  admission; public exposure needs TLS or the ssh:// transport.",
     "",
+    "  A cloud NAT/EIP host's public IP is on no NIC (--tls alone cannot",
+    "  cover it): add --tls-san <public-ip> next to --tls. Repeatable; DNS",
+    "  names accepted. The persisted certificate re-signs over the same key",
+    "  when a new entry appears — the pin is unchanged and pinned clients",
+    "  re-anchor transparently; dropping entries never re-signs.",
+    "",
   ].join("\n"),
 };
 
@@ -93,10 +103,19 @@ export interface ParsedServe {
   endpoint?: string;
   host: string;
   port: number;
+  /** Present = the --max-idle self-reap timer is armed (W9). */
+  maxIdleSeconds?: number;
+  /** Present = the systemd-passed listener (W10, Linux-only). */
+  systemdSocket?: boolean;
+  /** `--tls-san` values, normalized to `IP:x`/`DNS:y` SAN form (repeatable);
+   * valid only next to `--tls` — the execute layer enforces the pairing.
+   * Absent when the flag is not passed (parse output stays byte-identical
+   * to the pre-flag shape). */
+  tlsSan?: string[];
 }
 
 function toParsedServe(parsed: KitParsed): ParsedServe {
-  const options = parsed.options as { host?: string; port?: string; endpoint?: string };
+  const options = parsed.options as { host?: string; port?: string; endpoint?: string; maxIdle?: string; systemdSocket?: boolean; tlsSan?: string[] };
   const endpoint = options.endpoint;
   if (endpoint !== undefined && endpoint.length === 0) {
     throw new KitUsageError("--endpoint <name> must not be empty (omit it to serve a host door)");
@@ -106,7 +125,35 @@ function toParsedServe(parsed: KitParsed): ParsedServe {
   if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
     throw new KitUsageError("--port must be an integer between 1 and 65535");
   }
-  return { ...(endpoint !== undefined ? { endpoint } : {}), host, port };
+  const systemdSocket = options.systemdSocket === true;
+  if (systemdSocket && options.port !== undefined) {
+    throw new KitUsageError("--systemd-socket and --port are mutually exclusive (the socket unit owns the port)");
+  }
+  let maxIdleSeconds: number | undefined;
+  if (options.maxIdle !== undefined) {
+    maxIdleSeconds = Number(options.maxIdle);
+    if (!Number.isFinite(maxIdleSeconds) || maxIdleSeconds <= 0 || maxIdleSeconds > 86400) {
+      throw new KitUsageError("--max-idle must be a positive number of seconds (at most 86400)");
+    }
+  }
+  let tlsSan: string[] = [];
+  if (options.tlsSan !== undefined) {
+    try {
+      // normalized then deduplicated — case variants of one entry collapse
+      // here, so ParsedServe carries the canonical set
+      tlsSan = [...new Set(options.tlsSan.map(normalizeTlsSanEntry))];
+    } catch (error) {
+      throw new KitUsageError(error instanceof Error ? error.message : String(error));
+    }
+  }
+  return {
+    ...(endpoint !== undefined ? { endpoint } : {}),
+    host,
+    port,
+    ...(maxIdleSeconds !== undefined ? { maxIdleSeconds } : {}),
+    ...(systemdSocket ? { systemdSocket } : {}),
+    ...(tlsSan.length > 0 ? { tlsSan } : {}),
+  };
 }
 
 export function parseServeArgs(args: readonly string[]): ParsedServe {
@@ -122,10 +169,13 @@ export function renderServeBanner(info: ServeInfo): string {
     return [
       `serving host door (ukp-remote v1)`,
       `  listening: ${info.url}`,
-      `  discovery: ${info.url}${DISCOVERY_PATH} (host door)`,
+      `  discovery: ${info.url.startsWith("http") ? `${info.url}${DISCOVERY_PATH}` : info.url} (host door)`,
       `  endpoints: ${info.door!.endpoints.length > 0 ? info.door!.endpoints.join(", ") : "(none — register endpoints on this host)"}`,
       `  write: ${info.door!.write.length > 0 ? info.door!.write.join(", ") + " (propose via PUT /e/<name>/v1/propose/<id>)" : "(no endpoint declares propose)"}`,
       `  auth: ${info.authRequired ? "bearer token required" : "no token (loopback bind; ssh-forwarded clients authenticate by SSH key)"}`,
+      ...(info.maxIdleSeconds !== undefined
+        ? [`  idle: exits after ${info.maxIdleSeconds}s without requests (--max-idle)`]
+        : []),
       ...(info.tls !== undefined
         ? [`  tls: ${info.tls.source === "operator" ? "operator certificate" : `self-signed identity (${info.tls.source})`} ${info.tls.pin} (SAN: ${info.tls.san})`]
         : []),
@@ -135,8 +185,11 @@ export function renderServeBanner(info: ServeInfo): string {
   return [
     `serving endpoint '${info.endpoint}' (ukp-remote v1)`,
     `  listening: ${info.url}`,
-    `  discovery: ${info.url}${DISCOVERY_PATH}`,
+    `  discovery: ${info.url.startsWith("http") ? `${info.url}${DISCOVERY_PATH}` : info.url}`,
     `  auth: ${info.authRequired ? "bearer token required" : "no token (loopback only)"}`,
+    ...(info.maxIdleSeconds !== undefined
+      ? [`  idle: exits after ${info.maxIdleSeconds}s without requests (--max-idle)`]
+      : []),
     ...(info.tls !== undefined
       ? [`  tls: ${info.tls.source === "operator" ? "operator certificate" : `self-signed identity (${info.tls.source})`} ${info.tls.pin} (SAN: ${info.tls.san})`]
       : []),
@@ -173,24 +226,37 @@ export function executeServeCommand(
   context: ServeCommandContext,
 ): KitCommandResult {
   return executeKitCommand(SERVE_SPEC, args, (parsed) => {
-    const { endpoint, host, port } = toParsedServe(parsed);
+    const { endpoint, host, port, maxIdleSeconds, systemdSocket, tlsSan = [] } = toParsedServe(parsed);
     const allowAnonymous = (parsed.options as { allowAnonymous?: boolean }).allowAnonymous === true;
     const options = parsed.options as { tls?: boolean; tlsCert?: string; tlsKey?: string };
     // TLS flag family (W5'): --tls and --tls-cert/--tls-key are mutually
-    // exclusive; the explicit pair must arrive complete.
+    // exclusive; the explicit pair must arrive complete. --tls-san only
+    // shapes the self-signed generation — an operator certificate carries
+    // its own SAN, so the flag next to one is a mistake, not a no-op.
     if (options.tls === true && (options.tlsCert !== undefined || options.tlsKey !== undefined)) {
       throw new KitUsageError("--tls and --tls-cert/--tls-key are mutually exclusive");
     }
     if (options.tls !== true && (options.tlsCert !== undefined) !== (options.tlsKey !== undefined)) {
       throw new KitUsageError("--tls-cert and --tls-key are used together");
     }
+    if (tlsSan.length > 0 && options.tls !== true) {
+      throw new KitUsageError("--tls-san is only used with --tls (an explicit --tls-cert certificate carries its own SAN)");
+    }
     const tokens = context.tokens ?? parseServeTokens(process.env.UKP_SERVE_TOKEN);
+    // W10: socket activation must not admit tokenless serving — the bind
+    // address belongs to the socket unit (possibly public), so the loopback
+    // premise of --allow-anonymous is unverifiable here (RQ-18 review P1).
+    if (systemdSocket && tokens.length === 0) {
+      throw new Error(
+        "refusing to serve on --systemd-socket without a token: the listener's bind address belongs to the socket unit and may be public — tokenless loopback serving cannot be verified here; set UKP_SERVE_TOKEN",
+      );
+    }
     const decision = serveAuthDecision(host, tokens, allowAnonymous);
     if (!decision.ok) {
       const target = endpoint === undefined ? "host door" : `'${endpoint}'`;
       throw new Error(`refusing to serve ${target}: ${decision.reason}`);
     }
-    const { server, info } = startUkpServer({
+    const { server, info, stopAll } = startUkpServer({
       currentDirectory: context.currentDirectory,
       registryPath: context.registryPath,
       qmdCommand: context.qmdCommand,
@@ -198,18 +264,26 @@ export function executeServeCommand(
       port,
       ...(endpoint !== undefined ? { endpointName: endpoint } : {}),
       ...(tokens.length > 0 ? { tokens } : {}),
+      ...(maxIdleSeconds !== undefined ? { maxIdleSeconds } : {}),
+      ...(systemdSocket !== undefined && systemdSocket ? { systemdSocket } : {}),
       ...(options.tls === true
-        ? { tls: { mode: "self-signed" as const } }
+        ? { tls: { mode: "self-signed" as const, ...(tlsSan.length > 0 ? { sanEntries: tlsSan } : {}) } }
         : options.tlsCert !== undefined && options.tlsKey !== undefined
           ? { tls: { mode: "certificates" as const, certPath: options.tlsCert, keyPath: options.tlsKey } }
           : {}),
     });
     const stop = () => {
       console.error(`ukp serve: stopped (${info.url})`);
-      server.stop(true);
+      stopAll();
     };
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
+    // SIGHUP = the session died (client killed the ssh that woke this door).
+    // Bun IGNORES SIGHUP by default (ali E2E: every woken door survived its
+    // session and idled to max-idle) — the explicit handler restores the
+    // session-bound lifecycle; --max-idle stays the backstop for abnormal
+    // disconnects where no signal ever arrives. Never fires on Windows.
+    process.once("SIGHUP", stop);
     // Exit code 0 flows out through runCli; the server listener keeps the
     // process alive until the signal handler stops it.
     return { exitCode: 0, stdout: renderServeBanner(info), stderr: "" };

package/src/config/manifest.ts

@@ -147,6 +147,12 @@ export function loadManifest(serviceFolder: string): LoadedManifest {
   const normalized = normalizeFileNativeFlatKeys(withoutLegacyGet, (message) => {
     throw new ManifestError(message);
   });
+  if (isRecord(normalized) && !Object.hasOwn(normalized, "capabilities")) {
+    throw new ManifestError(
+      "Service Manifest schema is invalid: missing required [capabilities] table; "
+      + "use an empty [capabilities] table for the provider-free read/nav/rg baseline",
+    );
+  }
   const result = manifestSchema.safeParse(normalized);
   if (!result.success) {
     throw new ManifestError(`Service Manifest schema is invalid: ${result.error.message}`);

package/src/registry.ts

@@ -29,6 +29,12 @@ const bindingSchema = z.object({
   /** Client credential stored in the binding (D-078: plaintext, 0600 file —
    * AWS credentials-file / netrc convention; env override wins at call time). */
   token: z.string().min(1).optional(),
+  /** Remote-declared endpoint name snapshotted at registration
+   * (ADR-REM-007 / D-086): provenance and expected-assertion target. The
+   * binding's `name` is the consumer-chosen handle (defaults to the declared
+   * name); service identity stays with instance_uid / TLS pins. The profile
+   * check lives in validateBindings, next to `name` itself. */
+  declared_name: z.string().min(1).optional(),
   /** TLS trust anchor pinned at registration (W5' / D-079, self-signed
    * servers only — public-CA chains are not pinned): `tls_cert` is the PEM
    * used as the fetch trust anchor, `tls_pin` is the RFC 7469 SPKI pin that
@@ -53,6 +59,8 @@ export interface RegistryBinding {
   kind?: "remote";
   url?: string;
   instance_uid?: string;
+  /** Remote-declared name snapshot (ADR-REM-007 / D-086); see bindingSchema. */
+  declared_name?: string;
   /** Remote-only stored credential (plaintext; env takes precedence). */
   token?: string;
   /** Remote-only TLS anchor (W5' / D-079); see bindingSchema. */
@@ -197,6 +205,37 @@ export class RegistryError extends Error {
   }
 }
 
+/** Registration-only admission (D-089): since W9's on-demand wake an explicit
+ * port in an ssh:// url selects nothing — the woken door listens on a
+ * client-chosen loopback port — so intake rejects the dead grammar slot
+ * instead of documenting it (guide complexity attribution, D-087).
+ * Parse-time surfaces (parseRemoteUrl / assertRemoteUrlAllowed) stay
+ * permissive on purpose: bindings written by the resident-door era (W4–W8,
+ * e.g. `ssh://host:8571`) keep loading and calling; migrating one is an
+ * explicit unregister + register without the port (idempotency keys on the
+ * url, so an in-place refresh is not offered). */
+export function assertRegistrableRemoteUrl(raw: string): void {
+  assertRemoteUrlAllowed(raw);
+  // assertRemoteUrlAllowed returning without throwing means parseRemoteUrl is
+  // defined for this url — and new URL(raw) cannot throw either. No defensive
+  // try/catch: a rejection helper fails closed by construction.
+  const parts = parseRemoteUrl(raw)!;
+  const parsed = new URL(raw);
+  if (parts.scheme === "ssh" && parsed.port !== "") {
+    // The remedy is deliberately built portless from parts — `origin` would
+    // carry the rejected port right back into the suggestion. URL.hostname
+    // drops IPv6 brackets, so they are re-added for that shape.
+    const host = parts.host.includes(":") ? `[${parts.host}]` : parts.host;
+    const portless = `ssh://${parts.user !== undefined ? `${parts.user}@` : ""}${host}`
+      + `${parts.endpointName !== undefined ? `/${parts.endpointName}` : ""}`;
+    throw new RegistryError(
+      `ssh:// urls take no port: the woken door listens on a client-chosen loopback port and the url port selects nothing`
+        + ` — register '${portless}' instead`
+        + ` (for a non-standard sshd port, use an ssh config Host alias)`,
+    );
+  }
+}
+
 export class RegistryBusyError extends RegistryError {
   constructor(path: string) {
     super(
@@ -221,6 +260,9 @@ function validateBindings(endpoints: readonly RegistryBinding[]): RegistryBindin
       if (endpoint.url === undefined) {
         throw new RegistryError(`remote binding '${endpoint.name}' requires a url`);
       }
+      if (endpoint.declared_name !== undefined && !ENDPOINT_NAME.test(endpoint.declared_name)) {
+        throw new RegistryError(`remote binding '${endpoint.name}' carries an invalid declared name '${endpoint.declared_name}'`);
+      }
       if ((endpoint.tls_cert !== undefined) !== (endpoint.tls_pin !== undefined)) {
         throw new RegistryError(`remote binding '${endpoint.name}' must carry tls_cert and tls_pin together`);
       }
@@ -230,9 +272,10 @@ function validateBindings(endpoints: readonly RegistryBinding[]): RegistryBindin
     } else {
       if (
         endpoint.url !== undefined || endpoint.instance_uid !== undefined || endpoint.token !== undefined
+        || endpoint.declared_name !== undefined
         || endpoint.tls_cert !== undefined || endpoint.tls_pin !== undefined
       ) {
-        throw new RegistryError(`local binding '${endpoint.name}' must not carry remote fields (url/instance_uid/token/tls)`);
+        throw new RegistryError(`local binding '${endpoint.name}' must not carry remote fields (url/instance_uid/token/declared_name/tls)`);
       }
       if (endpoint.path === undefined || !isAbsolute(endpoint.path)) {
         throw new RegistryError(`registry path must be absolute: ${endpoint.path ?? "(missing)"}`);
@@ -273,14 +316,16 @@ export function readRegistry(registryPath: string): RegistryBinding[] {
 }
 
 /** Canonical serialization (configuration-contracts canonical form): local rows
- * `{name, path}`, remote rows `{name, kind, url, instance_uid?}` — key order
- * is insertion order, so build plain ordered objects before stringify. */
+ * `{name, path}`, remote rows `{name, kind, url, declared_name?, instance_uid?}`
+ * (plus credentials/pins when present) — key order is insertion order, so
+ * build plain ordered objects before stringify. */
 function toSerializableBinding(binding: RegistryBinding): Record<string, string> {
   if (binding.kind === "remote") {
     return {
       name: binding.name,
       kind: "remote",
       url: binding.url!,
+      ...(binding.declared_name !== undefined ? { declared_name: binding.declared_name } : {}),
       ...(binding.instance_uid !== undefined ? { instance_uid: binding.instance_uid } : {}),
       ...(binding.token !== undefined ? { token: binding.token } : {}),
       ...(binding.tls_cert !== undefined ? { tls_cert: binding.tls_cert } : {}),
@@ -316,8 +361,12 @@ export function registerBinding(endpoints: readonly RegistryBinding[], binding:
   return validateBindings([...endpoints, canonical]);
 }
 
-/** Remote registration (D-077): name comes from the discovery document
- * (RQ-14), instance_uid is the TOFU pin. Idempotent on same name+url. */
+/** Remote registration (D-077; naming residence ADR-REM-007 / D-086): the
+ * binding `name` is the consumer-chosen handle (defaults to the declared
+ * name), `declared_name` is the registration-time provenance snapshot.
+ * Idempotency keys on url+declared name → refresh under the EXISTING handle
+ * (N-2): one url, one handle; a second handle for the same instance goes
+ * through a different url and warns at list time, never here. */
 export function registerRemoteBinding(
   endpoints: readonly RegistryBinding[],
   binding: RegistryBinding,
@@ -326,26 +375,57 @@ export function registerRemoteBinding(
     name: binding.name,
     kind: "remote",
     url: binding.url!,
+    ...(binding.declared_name !== undefined ? { declared_name: binding.declared_name } : {}),
     ...(binding.instance_uid !== undefined ? { instance_uid: binding.instance_uid } : {}),
     ...(binding.token !== undefined ? { token: binding.token } : {}),
     ...(binding.tls_cert !== undefined ? { tls_cert: binding.tls_cert } : {}),
     ...(binding.tls_pin !== undefined ? { tls_pin: binding.tls_pin } : {}),
   };
+  // API-seam enforcement of the registration-only ssh port rule (D-089): the
+  // registry never gains a NEW ported ssh binding, while legacy ones keep
+  // loading (validateBindings uses the permissive parse-time check).
+  assertRegistrableRemoteUrl(canonical.url!);
+  const sameUrl = endpoints.find((endpoint) => endpoint.kind === "remote" && endpoint.url === canonical.url);
+  if (sameUrl) {
+    // Legacy bindings (pre-ADR-REM-007) carry no declared_name; their handle
+    // WAS the declared name under RQ-14, so the name stands in for it.
+    const existingDeclared = sameUrl.declared_name ?? sameUrl.name;
+    const incomingDeclared = canonical.declared_name ?? canonical.name;
+    if (existingDeclared !== incomingDeclared) {
+      throw new RegistryError(
+        `remote endpoint at ${canonical.url} now declares '${incomingDeclared}', but binding '${sameUrl.name}' was registered for '${existingDeclared}'; unregister '${sameUrl.name}' and re-register`,
+      );
+    }
+    if (canonical.name !== sameUrl.name && canonical.name !== incomingDeclared) {
+      // An explicitly different handle for an instance already tracked under
+      // this url: one url, one handle (rename = unregister + register).
+      throw new RegistryError(
+        `remote endpoint ${canonical.url} is already registered as '${sameUrl.name}'; unregister it first to change the handle`,
+      );
+    }
+    // Default gesture (handle = declared name) or matching handle: the
+    // idempotent refresh of the TOFU pin and credentials lands under the
+    // EXISTING handle (N-2 — service replacement stays an explicit
+    // unregister + re-register, ADR-REM-003). Direct-API callers that omit
+    // declared_name must not erase the stored snapshot (the CLI always
+    // passes it; the skip/refusal wording that mirrors this branch lives in
+    // importDoorEndpoints).
+    const refreshed: RegistryBinding = {
+      ...canonical,
+      ...(canonical.name !== sameUrl.name ? { name: sameUrl.name } : {}),
+      ...(canonical.declared_name === undefined && sameUrl.declared_name !== undefined
+        ? { declared_name: sameUrl.declared_name }
+        : {}),
+    };
+    return validateBindings([...endpoints.filter((e) => e.name !== sameUrl.name), refreshed]);
+  }
   const sameName = endpoints.find((endpoint) => endpoint.name === canonical.name);
   if (sameName) {
-    if (sameName.kind === "remote" && sameName.url === canonical.url) {
-      // Same name+url re-registration refreshes the TOFU pin (service
-      // replacement is an explicit re-register, ADR-REM-003).
-      return validateBindings([...endpoints.filter((e) => e.name !== canonical.name), canonical]);
-    }
     throw new RegistryError(
-      `endpoint name '${canonical.name}' is already bound to ${sameName.kind === "remote" ? sameName.url : sameName.path}`,
+      `endpoint name '${canonical.name}' is already bound to ${sameName.kind === "remote" ? sameName.url : sameName.path}; `
+        + `register this endpoint under another handle with --name <handle>`,
     );
   }
-  const sameUrl = endpoints.find((endpoint) => endpoint.kind === "remote" && endpoint.url === canonical.url);
-  if (sameUrl) {
-    throw new RegistryError(`remote endpoint url is already bound to '${sameUrl.name}'`);
-  }
   return validateBindings([...endpoints, canonical]);
 }
 
@@ -410,7 +490,15 @@ export function registerAt(registryPath: string, name: string, servicePath: stri
 
 export function registerRemoteAt(
   registryPath: string,
-  binding: { name: string; url: string; instance_uid?: string; token?: string; tls_cert?: string; tls_pin?: string },
+  binding: {
+    name: string;
+    url: string;
+    declared_name?: string;
+    instance_uid?: string;
+    token?: string;
+    tls_cert?: string;
+    tls_pin?: string;
+  },
 ): RegistryBinding[] {
   return mutateRegistry(registryPath, (current) => registerRemoteBinding(current, binding));
 }