SIGNED_DOMAINSconstno test imports itconst SIGNED_DOMAINS: readonly ["anyfs-delta/1", "anyfs-epoch/1", "anyfs-dump/1"]What a signature is for: the domain written before the digest.
The signature of what replicas exchange: a delta, an epoch and a dump are each named by a digest, and a replica that signs says in its own key that it made what the digest names. The key is Ed25519 (the algorithm of the keys the commons already signs with, and the one both runtimes hold); a signature is the text ed25519:<key id>:<base64>, where the key id is the first 16 hexadecimal digits of the SHA-256 of the 32 bytes of the public key; and what is signed is the digest with the domain it is for and the replica that made it (anyfs-delta/1, anyfs-epoch/1, anyfs-dump/1), so that a signature of one thing is never a signature of another. A roster says which keys speak for which replica and when: each entry has a window (not before, not after, in milliseconds), so that a key can be replaced and a delta signed under the old key still holds for the time it was made in.
import { generateSigningKey, makeSigner, rosterTrust, signDelta } from "./signing.ts";
const key = await generateSigningKey(replica);
const signed = await signDelta(delta, await makeSigner(key));
const trust = rosterTrust([key.entry]);SIGNED_DOMAINSconstno test imports itconst SIGNED_DOMAINS: readonly ["anyfs-delta/1", "anyfs-epoch/1", "anyfs-dump/1"]What a signature is for: the domain written before the digest.
SignedDomaintypeno test imports ittype SignedDomain = (typeof SIGNED_DOMAINS)[number];One domain of a signature.
SIGNATURE_ALGORITHMconstno test imports itconst SIGNATURE_ALGORITHM: "ed25519"The prefix of a signature's text.
KeyEntrytypeno test imports ittype KeyEntry = {
readonly replica: ReplicaId;
readonly keyId: string;
readonly publicKey: string;
readonly notBefore?: number;
readonly notAfter?: number;
};One key that speaks for a replica, and when: the 32 bytes of the public key in base64, with the window in milliseconds it speaks in.
KeyRostertypeno test imports ittype KeyRoster = readonly KeyEntry[];The keys a replica knows.
Signertypeno test imports ittype Signer = {
readonly replica: ReplicaId;
readonly keyId: string;
sign(domain: SignedDomain, text: string): Promise<string>;
};Whoever signs: the replica and key they speak with, and the signing of a text.
PrivateJwktypeno test imports ittype PrivateJwk = {
readonly kty?: string;
readonly crv?: string;
readonly x?: string;
readonly d?: string;
readonly ext?: boolean;
readonly key_ops?: string[];
};The private key of a replica as a JSON Web Key (RFC 8037, Ed25519): declared here, so that no consumer needs the dom library for a type of it.
SigningKeytypeno test imports ittype SigningKey = { readonly privateJwk: PrivateJwk; readonly entry: KeyEntry };A key pair made for a replica: the private key as a JWK (to be kept as a secret), the roster entry to give to others, and the signer.
keyIdOffunctionfunction keyIdOf(publicRaw: Uint8Array<ArrayBufferLike>): Promise<string>The id of a key: the first 16 hexadecimal digits of the SHA-256 of its 32 bytes.
generateSigningKeyfunctionfunction generateSigningKey(replica: ReplicaId, window?: { readonly notBefore?: number | undefined; readonly notAfter?: number | undefined; }): Promise<SigningKey>A new key pair for a replica.
messageOfconstconst messageOf: (domain: "anyfs-delta/1" | "anyfs-dump/1" | "anyfs-epoch/1", replica: ReplicaId, digest: string) => stringThe message that is signed: the domain, the replica that made the thing, and its digest, each on a line.
makeSignerfunctionfunction makeSigner(key: SigningKey): Promise<Signer>A signer from a private key (a JWK) and the entry it belongs to.
signDeltafunctionno test imports itfunction signDelta(delta: Delta, signer: Signer): Promise<Delta>A delta with the signature of the replica that made it: the signature is over the identity of the delta, which is made without it.
parseSignaturefunctionfunction parseSignature(signature: string): Result<{ readonly keyId: string; readonly bytes: Uint8Array<ArrayBufferLike>; }, string>The parts of a signature's text, or why it is not one.
verifySignedfunctionfunction verifySigned(roster: KeyRoster, domain: "anyfs-delta/1" | "anyfs-dump/1" | "anyfs-epoch/1", digest: string, signature: string, replica: ReplicaId, at: number): Promise<"bad-signature" | "ok" | "unknown-key">Whether a signature holds for a thing a replica made at a time: the verdict, and the reason where it is not ok.
rosterTrustfunctionfunction rosterTrust(roster: KeyRoster, replicas?: ReadonlySet<ReplicaId> | undefined): TrustThe trust that takes deltas signed by a key of the roster, from the replicas the roster names alone unless replicas narrows them (a replica must be on both).
parseRosterfunctionfunction parseRoster(source: string): Result<KeyRoster, string>A roster read from text: a JSON list of entries, each checked, or why the text is not a roster.
rosterTextconstconst rosterText: (roster: KeyRoster) => stringThe text of a roster: what parseRoster reads.
signingKeyTextconstconst signingKeyText: (key: SigningKey) => stringA signing key as it is kept in a file: the replica it speaks for, the roster entry others add to their roster, and the private key. The file is a secret and is never written to a command line.
parseSigningKeyfunctionfunction parseSigningKey(source: string): Result<SigningKey, string>A signing key read from a file's text, or why the text is not one.
signDeltaByfunctionno test imports itfunction signDeltaBy(delta: Delta, signers: readonly Signer[]): Promise<Delta>A delta signed by the signer of its origin among several, as it is signed where more than one replica's key is in hand; a delta whose origin has no signer here is returned as it is, unsigned.