- 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>
74 lines
3.7 KiB
TypeScript
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;
|