Files
crosscode-platform/packages/contracts/src/link.ts
T
joshuaandClaude Opus 5.5 4952e2cb0f Contracts 1.4.0: crosscode.link/1 and a public key in the v2 heartbeat
- crosscode.link/1 (link.connect / link.connected / link.disconnect), with
  signLink / verifyLink, PEM conversion, link secrets and nonces.
- The v2 heartbeat can carry the install's publicKey; the reply says
  saved / matches / mismatch (Hub 2.2.0). Never a failed heartbeat.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 11:58:26 +02:00

74 lines
3.7 KiB
TypeScript

import { z } from "zod";
import { dateTimeSchema, idSchema, productSchema, urlSchema } from "./common";
import { schemaName } from "./schema-name";
/**
* `crosscode.link/1` — **Connect** under Settings → Linked products (docs/EVENTS-2.4-PLAN.md §2).
*
* The Hub tells each install which of its church's other installs exist and their Ed25519 public
* keys (`linkedProducts` in the heartbeat reply). Connect turns that into a working link between
* two of them: a shared secret for signed calls (`LINK_HEADERS` in `@crosscode/contracts/signing`:
* the `event.changed` webhook, later Accounts' back-channel calls).
*
* ```
* A → POST {B.url}/api/links/v1/connect link.connect (signed by A, carries the new secret)
* ← 200 link.connected (signed by B, echoes A's nonce)
* A → POST {B.url}/api/links/v1/disconnect link.disconnect (signed by A)
* ← 200 link.disconnected
* ```
*
* B accepts A only when A is in **B's own cached** `linkedProducts` with the key that signed the
* message, so only installs of the same church can link, and the Hub isn't on the path at the time
* of the call. Signatures are Ed25519 over the message without `signature`, as canonical JSON
* (`signLink` / `verifyLink`). Messages more than five minutes off the receiver's clock are
* refused, and a nonce is only accepted once.
*/
export const LINK_SCHEMA = schemaName("link", 1);
/** Where the endpoints live on every product, relative to its address. */
export const LINK_PATHS = { connect: "/api/links/v1/connect", disconnect: "/api/links/v1/disconnect" } as const;
export const LINK_ERROR_CODES = ["NOT_LINKED", "WRONG_INSTALL", "BAD_SIGNATURE", "STALE_REQUEST", "REPLAYED", "INVALID_REQUEST", "LINKS_UNAVAILABLE"] as const;
export const linkPartySchema = z.object({
product: productSchema,
installId: idSchema,
url: urlSchema,
});
export type LinkParty = z.infer<typeof linkPartySchema>;
/** 32 random bytes, base64url without padding. */
export const linkSecretSchema = z.string().regex(/^[A-Za-z0-9_-]{43}$/, "Expected 32 bytes, base64url");
const nonceSchema = z.string().regex(/^[A-Za-z0-9_-]{22,64}$/, "Expected a random base64url nonce");
const signatureSchema = z.string().regex(/^[A-Za-z0-9_-]{86}$/, "Expected an Ed25519 signature, base64url");
const signed = {
schema: z.literal(LINK_SCHEMA),
from: linkPartySchema,
to: z.object({ installId: idSchema }),
issuedAt: dateTimeSchema,
nonce: nonceSchema,
signature: signatureSchema,
};
/** A asks B to link, and hands it the secret both will sign calls with. */
export const linkConnectSchema = z.object({ ...signed, type: z.literal("link.connect"), secret: linkSecretSchema });
export type LinkConnect = z.infer<typeof linkConnectSchema>;
/** B's answer: signed by B and echoing A's nonce, so A knows the real B stored the secret. */
export const linkConnectedSchema = z.object({ ...signed, type: z.literal("link.connected"), inReplyTo: nonceSchema });
export type LinkConnected = z.infer<typeof linkConnectedSchema>;
/** Either side ends the link; both drop the secret. */
export const linkDisconnectSchema = z.object({ ...signed, type: z.literal("link.disconnect") });
export type LinkDisconnect = z.infer<typeof linkDisconnectSchema>;
export const linkDisconnectedSchema = z.object({ schema: z.literal(LINK_SCHEMA), type: z.literal("link.disconnected") });
export type LinkDisconnected = z.infer<typeof linkDisconnectedSchema>;
export const linkErrorSchema = z.object({ message: z.string(), code: z.enum(LINK_ERROR_CODES) });
export type LinkError = z.infer<typeof linkErrorSchema>;
export type LinkMessage = LinkConnect | LinkConnected | LinkDisconnect;