@openlfcp/wire 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/** Name of this package. */
+export declare const PACKAGE = "@openlfcp/wire";
+export { ABILITY, ABILITY_NAMES, type Authorization, abilitiesOf, authorizeControlRecord, type CapabilityState, canDistributeKey, type Grant, hasAbility, isGrantActive, isStandardAbility, type VerifiedOwnerTransfer, verifyOwnerTransfer, } from "./capability.js";
+export { type ChainOptions, type ChainProblem, type ChainResult, type ControlEpoch, type ControlRoute, type ControlState, type EpochHistory, validateControlChain, } from "./chain.js";
+export { type ControlBody, type ControlBodyType, type ControlRecord, type ControlRecordHeader, controlBodyFromCbor, controlBodyToCbor, controlRecordSigner, controlTypeOf, decodeControlRecord, encodeControlRecordPayload, isMvpSupported, type OwnerTransferAcceptPayload, type OwnerTransferOfferPayload, ownerTransferAcceptPayloadFromCbor, ownerTransferOfferPayloadFromCbor, parseOwnerTransferAccept, parseOwnerTransferOffer, type SignedControlRecord, signControlRecord, verifyGenesis, } from "./control.js";
+export { type ControlSyncPlan, type LocalControl, localControlOf, planControlSync, } from "./control-sync.js";
+export { COSE_ALG_EDDSA, objectId, parseSignedObject, type SignedBytes, type SignedObject, type Signer, signObject, sigStructureBytes, type VerifyResult, verifySignedObject, } from "./cose.js";
+export { checkDataUnit, type DataProfileCodec, type DataUnitAadFields, type DataUnitCheck, type DataUnitCheckOptions, type DataUnitEquivocation, type DataUnitHoldReason, type DataUnitQuarantined, type DataUnitRejected, type DataUnitRejectReason, dataUnitAad, encodeDataUnitPayload, InMemorySeenUnits, type ReceiveDataUnitOptions, type ReceivedDataUnit, receiveDataUnit, type SealedDataUnit, type SeenRecord, type SeenUnits, sealDataUnit, } from "./data-unit.js";
+export { checkReceivedUrl, checkWriterUrl, ENDPOINT_FLAGS, type Endpoint, endpointFromCbor, endpointToCbor, } from "./endpoint.js";
+export { type ControlView, classifyDataUnit, type DataPutDecision, type DataUnitHeader, type EpochClassification, type EpochRotation, isSequenceWithinFrontier, KEY_EPOCH_REASON, rotateEpoch, serverAcceptsDataPut, } from "./epoch.js";
+export { type AuthenticatedSession, type AuthProofCheck, type AuthTranscriptFields, authTranscript, type ClientHandshakeConfig, type ClientSession, type ClientStep, clientReceive, decodeAuthTranscript, isResourceMessage, type RandomSource, type ReadySession, type ServerHandshakeConfig, type ServerSession, type ServerStep, selectWireProfile, serverReceive, signAuthProof, startClientHandshake, startServerSession, verifyAuthProof, WIRE_PROFILE, } from "./handshake.js";
+export { type ActorHave, type ActorRange, actorHaveFromCbor, actorHaveToCbor, addRange, addSequence, batchDataRanges, canonicalFrontierFromCbor, canonicalFrontierToCbor, checkLiveHave, type HaveVector, hasSequence, type LiveHaveEntry, liveHavesOf, MAX_DATA_GET_RANGES, missingAfter, missingFrom, normalizeLiveHaves, type SequenceRange, unionHaves, } from "./have.js";
+export { assembleInviteUri, decodeInviteSecret, encodeInviteSecret, INVITE_SECRET_VERSION, type Invitation, invitationPrincipal, parseInviteUri, verifyInvitationSecret, } from "./invite.js";
+export { type KeyPackageCheck, type KeyPackageRecipient, keyPackageHpkeAad, keyPackageHpkeInfo, openKeyPackage, type ReceivedKeyPackage, receiveKeyPackage, type SealedKeyPackage, sealKeyPackage, verifyKeyPackage, } from "./key-package.js";
+export { type AckBody, type AnyMessage, type AuthBody, type ChallengeBody, type ControlGetBody, type ControlHaveBody, type ControlHeadRef, type CoreMessageType, createMessage, type DataGetBody, type DataHaveBody, type DataRange, DEFAULT_MAX_MESSAGE_BYTES, type DecodedEnvelope, type DecodeOptions, decodeEnvelope, decodeFrame, decodeMessage, ERROR_CODE, type ErrorBody, type ExtensionMessage, encodeMessage, FIRST_EXTENSION_MESSAGE_TYPE, type Frame, type FrameResult, type HelloBody, type KeyPackageGetBody, type LfcpMessage, type LiveActorHave, MESSAGE_TYPE, type MessageBodies, messageErrorWireCode, newMessageId, type ObjectListBody, type PingBody, type PresenceBody, type PresenceLeaveBody, type ReadyBody, type ResourceBody, type ResourceHostBody, type ResourceHostedBody, type ResourceOpenBody, type ResourceOpenedBody, replyTo, type SnapshotBody, type SnapshotGetBody, type SnapshotSummary, type WireErrorName, } from "./message.js";
+export { CONTROL_TYPE, type ControlRecordPayload, controlRecordPayloadFromCbor, type DataUnitPayload, dataUnitPayloadFromCbor, decodeControlRecordPayload, decodeDataUnitPayload, decodeKeyPackagePayload, decodeSnapshotPayload, expectedSignerOf, type KeyPackagePayload, keyPackagePayloadFromCbor, type Parsed, parseControlRecord, parseDataUnit, parseKeyPackage, parseSnapshot, type SnapshotPayload, snapshotPayloadFromCbor, } from "./objects.js";
+export { decodePrincipalDescriptor, derivePrincipalId, encodePrincipalDescriptor, type PrincipalDescriptor, principalDescriptor, principalDescriptorFromCbor, principalDescriptorFromKeys, principalDescriptorToCbor, } from "./principal.js";
+export { type ClientConnectionEvent, type ClientConnectionState, clientConnectionTransition, type ServerSessionEvent, type ServerSessionState, serverSessionTransition, } from "./session-state.js";
+export { beyondCutoff, checkSnapshot, encodeSnapshotPayload, type ReceivedSnapshot, type ReceiveSnapshotOptions, receiveSnapshot, type SealedSnapshot, type SnapshotAadFields, type SnapshotCheck, type SnapshotCheckOptions, type SnapshotRejected, type SnapshotRejectReason, sealSnapshot, snapshotAad, } from "./snapshot.js";
+export { type ControlPutBody, controlPutBodyFromCbor, decodeControlPutBody, proposeControlPut, proposeControlTransition, type TransitionResult, } from "./transition.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,21 @@
+/** Name of this package. */
+export const PACKAGE = "@openlfcp/wire";
+export { ABILITY, ABILITY_NAMES, abilitiesOf, authorizeControlRecord, canDistributeKey, hasAbility, isGrantActive, isStandardAbility, verifyOwnerTransfer, } from "./capability.js";
+export { validateControlChain, } from "./chain.js";
+export { controlBodyFromCbor, controlBodyToCbor, controlRecordSigner, controlTypeOf, decodeControlRecord, encodeControlRecordPayload, isMvpSupported, ownerTransferAcceptPayloadFromCbor, ownerTransferOfferPayloadFromCbor, parseOwnerTransferAccept, parseOwnerTransferOffer, signControlRecord, verifyGenesis, } from "./control.js";
+export { localControlOf, planControlSync, } from "./control-sync.js";
+export { COSE_ALG_EDDSA, objectId, parseSignedObject, signObject, sigStructureBytes, verifySignedObject, } from "./cose.js";
+export { checkDataUnit, dataUnitAad, encodeDataUnitPayload, InMemorySeenUnits, receiveDataUnit, sealDataUnit, } from "./data-unit.js";
+export { checkReceivedUrl, checkWriterUrl, ENDPOINT_FLAGS, endpointFromCbor, endpointToCbor, } from "./endpoint.js";
+export { classifyDataUnit, isSequenceWithinFrontier, KEY_EPOCH_REASON, rotateEpoch, serverAcceptsDataPut, } from "./epoch.js";
+export { authTranscript, clientReceive, decodeAuthTranscript, isResourceMessage, selectWireProfile, serverReceive, signAuthProof, startClientHandshake, startServerSession, verifyAuthProof, WIRE_PROFILE, } from "./handshake.js";
+export { actorHaveFromCbor, actorHaveToCbor, addRange, addSequence, batchDataRanges, canonicalFrontierFromCbor, canonicalFrontierToCbor, checkLiveHave, hasSequence, liveHavesOf, MAX_DATA_GET_RANGES, missingAfter, missingFrom, normalizeLiveHaves, unionHaves, } from "./have.js";
+export { assembleInviteUri, decodeInviteSecret, encodeInviteSecret, INVITE_SECRET_VERSION, invitationPrincipal, parseInviteUri, verifyInvitationSecret, } from "./invite.js";
+export { keyPackageHpkeAad, keyPackageHpkeInfo, openKeyPackage, receiveKeyPackage, sealKeyPackage, verifyKeyPackage, } from "./key-package.js";
+export { createMessage, DEFAULT_MAX_MESSAGE_BYTES, decodeEnvelope, decodeFrame, decodeMessage, ERROR_CODE, encodeMessage, FIRST_EXTENSION_MESSAGE_TYPE, MESSAGE_TYPE, messageErrorWireCode, newMessageId, replyTo, } from "./message.js";
+export { CONTROL_TYPE, controlRecordPayloadFromCbor, dataUnitPayloadFromCbor, decodeControlRecordPayload, decodeDataUnitPayload, decodeKeyPackagePayload, decodeSnapshotPayload, expectedSignerOf, keyPackagePayloadFromCbor, parseControlRecord, parseDataUnit, parseKeyPackage, parseSnapshot, snapshotPayloadFromCbor, } from "./objects.js";
+export { decodePrincipalDescriptor, derivePrincipalId, encodePrincipalDescriptor, principalDescriptor, principalDescriptorFromCbor, principalDescriptorFromKeys, principalDescriptorToCbor, } from "./principal.js";
+export { clientConnectionTransition, serverSessionTransition, } from "./session-state.js";
+export { beyondCutoff, checkSnapshot, encodeSnapshotPayload, receiveSnapshot, sealSnapshot, snapshotAad, } from "./snapshot.js";
+export { controlPutBodyFromCbor, decodeControlPutBody, proposeControlPut, proposeControlTransition, } from "./transition.js";
+//# sourceMappingURL=index.js.map

package/dist/invite.d.ts

@@ -0,0 +1,80 @@
+import { type ControlRecordId, type ResourceId } from "@openlfcp/core";
+import { InvitationSecret } from "@openlfcp/crypto";
+import type { ControlState } from "./chain.js";
+import type { Signer } from "./cose.js";
+import { type PrincipalDescriptor } from "./principal.js";
+/**
+ * Invitations (LFCP-WIRE-01 §18, §18.2, LFCP-039b): the invitation secret
+ * (deterministic CBOR of the Invitation Principal's private keys), the
+ * Invitation Principal it determines, and the canonical lfcp://join URI in
+ * its targeted and bearer forms. Pure building blocks; the claim flow
+ * (CAPABILITY_CLAIM, the claimant's Key Package) is LFCP-053.
+ *
+ * §18.2: the secret "MUST NOT be logged, placed in analytics, stored in
+ * browser history by an LFCP web landing page, or transmitted to the
+ * synchronization server as an opaque URL." An InvitationSecret is
+ * redacted when printed or serialized, and no error raised here includes
+ * a URI, a secret or key bytes: messages name the part that is wrong only.
+ * A bearer URI string itself carries the secret; treat it like a key.
+ */
+/** §18.2 invite-secret field 0: the only secret format version. */
+export declare const INVITE_SECRET_VERSION = 1n;
+/**
+ * The §18.2 invite-secret: deterministic CBOR {0: 1, 1: Ed25519 seed,
+ * 2: X25519 private key}.
+ *
+ * WARNING: the result is secret. It belongs only in the `#secret=`
+ * fragment of a bearer invitation URI handed to the invitee.
+ */
+export declare function encodeInviteSecret(secret: InvitationSecret): Uint8Array;
+/**
+ * Decodes a §18.2 invite-secret: deterministic CBOR, exactly fields 0-2,
+ * version 1 and two 32-byte keys. Throws INVALID_INVITATION, never with
+ * the bytes in the message.
+ */
+export declare function decodeInviteSecret(bytes: Uint8Array): InvitationSecret;
+/** The Invitation Principal's public descriptor, recomputed from its secret (§7, §18.2). */
+export declare function invitationPrincipal(secret: InvitationSecret): PrincipalDescriptor;
+/**
+ * §18.2: "The receiving client MUST recompute the corresponding public
+ * Principal Descriptor and MUST verify that it matches the subject of the
+ * referenced Invitation Grant before using the secret."
+ *
+ * `grantId` must name a grant of `state` (MISSING_DEPENDENCY otherwise: the
+ * client lacks Control Records) that lists invite/claim (§18: an
+ * invitation grant), whose subject is the recomputed Invitation Principal
+ * (INVALID_INVITATION otherwise). Returns the Invitation Principal as a
+ * signer, for the claim record (§18.1). Whether the grant is still active
+ * and claimable is decided where it is used (§18.1, §25.2).
+ */
+export declare function verifyInvitationSecret(state: ControlState, grantId: ControlRecordId, secret: InvitationSecret): Signer;
+/** An invitation: the targeted form, or the bearer form when `secret` is present (§18.2). */
+export interface Invitation {
+    readonly resourceId: ResourceId;
+    /** One or more endpoint URLs, in URI order. */
+    readonly endpoints: readonly string[];
+    /** The Control Record ID of the invitation grant. */
+    readonly grantId: ControlRecordId;
+    readonly secret?: InvitationSecret;
+}
+/**
+ * The canonical §18.2 URI: lfcp://join/<resource>?endpoint=…[&endpoint=…]&grant=<grant>,
+ * plus #secret=<secret> for a bearer invitation. IDs and the secret are
+ * unpadded base64url; each endpoint must pass the §16 writer rules and is
+ * percent-encoded (G-RS4).
+ */
+export declare function assembleInviteUri(invitation: Invitation): string;
+/**
+ * Parses a §18.2 invitation URI. The scheme and host compare
+ * case-insensitively (RFC 3986 §3.1, §3.2.2); the path is one Resource ID;
+ * the query has one or more `endpoint` parameters and exactly one `grant`;
+ * other parameters are ignored, for forward compatibility, once their
+ * percent-encoding is checked; a fragment, if present, is exactly
+ * `secret=<b64url>`.
+ * Endpoints are percent-decoded and must use ws or wss (§16). Throws
+ * INVALID_INVITATION, never with the URI or the secret in the message.
+ * Verify a bearer secret against the grant (verifyInvitationSecret) before
+ * using it.
+ */
+export declare function parseInviteUri(uri: string): Invitation;
+//# sourceMappingURL=invite.d.ts.map

package/dist/invite.js

@@ -0,0 +1,247 @@
+import { bytesEqual, controlRecordId, fromBase64url, LfcpError, resourceId, toBase64url, toHex, } from "@openlfcp/core";
+import { exportSecretKeyBytes, InvitationSecret, importAgreementKey, importSigningKey, } from "@openlfcp/crypto";
+import { ABILITY } from "./capability.js";
+import { cborMap, decodeDeterministic, encode } from "./cbor/index.js";
+import { strictUtf8Decoder, utf8Encoder } from "./cbor/text.js";
+import { checkReceivedUrl, checkWriterUrl } from "./endpoint.js";
+import { Fields } from "./fields.js";
+import { principalDescriptorFromKeys } from "./principal.js";
+/**
+ * Invitations (LFCP-WIRE-01 §18, §18.2, LFCP-039b): the invitation secret
+ * (deterministic CBOR of the Invitation Principal's private keys), the
+ * Invitation Principal it determines, and the canonical lfcp://join URI in
+ * its targeted and bearer forms. Pure building blocks; the claim flow
+ * (CAPABILITY_CLAIM, the claimant's Key Package) is LFCP-053.
+ *
+ * §18.2: the secret "MUST NOT be logged, placed in analytics, stored in
+ * browser history by an LFCP web landing page, or transmitted to the
+ * synchronization server as an opaque URL." An InvitationSecret is
+ * redacted when printed or serialized, and no error raised here includes
+ * a URI, a secret or key bytes: messages name the part that is wrong only.
+ * A bearer URI string itself carries the secret; treat it like a key.
+ */
+/** §18.2 invite-secret field 0: the only secret format version. */
+export const INVITE_SECRET_VERSION = 1n;
+const KEY_LENGTH = 32;
+const ID_LENGTH = 32;
+const PREFIX = "lfcp://join/";
+const invalid = (why) => {
+    throw new LfcpError("INVALID_INVITATION", `invalid invitation: ${why}`);
+};
+/**
+ * The §18.2 invite-secret: deterministic CBOR {0: 1, 1: Ed25519 seed,
+ * 2: X25519 private key}.
+ *
+ * WARNING: the result is secret. It belongs only in the `#secret=`
+ * fragment of a bearer invitation URI handed to the invitee.
+ */
+export function encodeInviteSecret(secret) {
+    return encode(cborMap([
+        [0, INVITE_SECRET_VERSION],
+        [1, exportSecretKeyBytes(secret.signingKey)],
+        [2, exportSecretKeyBytes(secret.agreementKey)],
+    ]));
+}
+/**
+ * Decodes a §18.2 invite-secret: deterministic CBOR, exactly fields 0-2,
+ * version 1 and two 32-byte keys. Throws INVALID_INVITATION, never with
+ * the bytes in the message.
+ */
+export function decodeInviteSecret(bytes) {
+    let fields;
+    try {
+        fields = new Fields(decodeDeterministic(bytes), "invite-secret", [0, 1, 2]);
+        if (fields.uint(0) !== INVITE_SECRET_VERSION)
+            fields.fail(0, `must be secret format version ${INVITE_SECRET_VERSION}`);
+        return InvitationSecret.fromKeys(importSigningKey(fields.bytes(1, KEY_LENGTH)), importAgreementKey(fields.bytes(2, KEY_LENGTH)));
+    }
+    catch (e) {
+        // Only the error code: no message that could quote a value.
+        const code = e instanceof LfcpError ? e.code : "UNKNOWN";
+        return invalid(`the secret is not a §18.2 invite-secret (${code})`);
+    }
+}
+/** The Invitation Principal's public descriptor, recomputed from its secret (§7, §18.2). */
+export function invitationPrincipal(secret) {
+    return principalDescriptorFromKeys(secret.signingKey, secret.agreementKey);
+}
+/**
+ * §18.2: "The receiving client MUST recompute the corresponding public
+ * Principal Descriptor and MUST verify that it matches the subject of the
+ * referenced Invitation Grant before using the secret."
+ *
+ * `grantId` must name a grant of `state` (MISSING_DEPENDENCY otherwise: the
+ * client lacks Control Records) that lists invite/claim (§18: an
+ * invitation grant), whose subject is the recomputed Invitation Principal
+ * (INVALID_INVITATION otherwise). Returns the Invitation Principal as a
+ * signer, for the claim record (§18.1). Whether the grant is still active
+ * and claimable is decided where it is used (§18.1, §25.2).
+ */
+export function verifyInvitationSecret(state, grantId, secret) {
+    const grant = state.grants.get(toHex(grantId));
+    if (grant === undefined)
+        throw new LfcpError("MISSING_DEPENDENCY", "the invitation's grant is not in the known Control Chain");
+    if (!grant.abilities.includes(ABILITY.INVITE_CLAIM))
+        invalid("the referenced grant is not an invitation grant (no invite/claim, §18)");
+    const descriptor = invitationPrincipal(secret);
+    if (!bytesEqual(descriptor.principalId, grant.subject))
+        invalid("the secret's Invitation Principal is not the subject of the grant (§18.2)");
+    return Object.freeze({ key: secret.signingKey, descriptor });
+}
+const UNRESERVED = /^[A-Za-z0-9\-._~]$/;
+/** §18.2 (G-RS4): every UTF-8 byte outside the RFC 3986 unreserved set as %XX, upper-case hex. */
+function percentEncode(text) {
+    let out = "";
+    for (const ch of text) {
+        if (UNRESERVED.test(ch))
+            out += ch;
+        else
+            for (const b of utf8Encoder.encode(ch))
+                out += `%${b.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+    return out;
+}
+/** RFC 3986 percent-decoding of a query value into UTF-8 text. */
+function percentDecode(text, what) {
+    const bytes = [];
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === "%") {
+            const hex = text.slice(i + 1, i + 3);
+            if (!/^[0-9A-Fa-f]{2}$/.test(hex))
+                invalid(`${what} has a broken percent-encoding`);
+            bytes.push(Number.parseInt(hex, 16));
+            i += 2;
+        }
+        else {
+            const code = ch.charCodeAt(0);
+            if (code < 0x21 || code > 0x7e)
+                invalid(`${what} has a character that must be percent-encoded`);
+            bytes.push(code);
+        }
+    }
+    try {
+        return strictUtf8Decoder.decode(Uint8Array.from(bytes));
+    }
+    catch {
+        return invalid(`${what} is not UTF-8`);
+    }
+}
+/** A canonical unpadded base64url 32-byte ID (§18.2). */
+function id32(text, what) {
+    let bytes;
+    try {
+        bytes = fromBase64url(text);
+    }
+    catch {
+        return invalid(`${what} is not canonical unpadded base64url`);
+    }
+    if (bytes.length !== ID_LENGTH)
+        invalid(`${what} is not ${ID_LENGTH} bytes`);
+    return bytes;
+}
+/**
+ * The canonical §18.2 URI: lfcp://join/<resource>?endpoint=…[&endpoint=…]&grant=<grant>,
+ * plus #secret=<secret> for a bearer invitation. IDs and the secret are
+ * unpadded base64url; each endpoint must pass the §16 writer rules and is
+ * percent-encoded (G-RS4).
+ */
+export function assembleInviteUri(invitation) {
+    if (invitation.endpoints.length === 0)
+        invalid("at least one endpoint is required (§18.2)");
+    for (const url of invitation.endpoints) {
+        try {
+            checkWriterUrl(url);
+        }
+        catch {
+            invalid("an endpoint is not a URL a writer may use (§16)");
+        }
+    }
+    const query = [
+        ...invitation.endpoints.map((url) => `endpoint=${percentEncode(url)}`),
+        `grant=${toBase64url(invitation.grantId)}`,
+    ].join("&");
+    const fragment = invitation.secret === undefined
+        ? ""
+        : `#secret=${toBase64url(encodeInviteSecret(invitation.secret))}`;
+    return `${PREFIX}${toBase64url(invitation.resourceId)}?${query}${fragment}`;
+}
+/**
+ * Parses a §18.2 invitation URI. The scheme and host compare
+ * case-insensitively (RFC 3986 §3.1, §3.2.2); the path is one Resource ID;
+ * the query has one or more `endpoint` parameters and exactly one `grant`;
+ * other parameters are ignored, for forward compatibility, once their
+ * percent-encoding is checked; a fragment, if present, is exactly
+ * `secret=<b64url>`.
+ * Endpoints are percent-decoded and must use ws or wss (§16). Throws
+ * INVALID_INVITATION, never with the URI or the secret in the message.
+ * Verify a bearer secret against the grant (verifyInvitationSecret) before
+ * using it.
+ */
+export function parseInviteUri(uri) {
+    if (typeof uri !== "string")
+        invalid("the URI is not a string");
+    if (uri.slice(0, PREFIX.length).toLowerCase() !== PREFIX)
+        invalid("the URI does not start with lfcp://join/");
+    const hash = uri.indexOf("#");
+    const beforeFragment = hash === -1 ? uri : uri.slice(0, hash);
+    const question = beforeFragment.indexOf("?");
+    if (question === -1)
+        invalid("the URI has no query");
+    const path = beforeFragment.slice(PREFIX.length, question);
+    const resource = resourceId(id32(path, "the Resource ID"));
+    const endpoints = [];
+    let grant;
+    for (const parameter of beforeFragment.slice(question + 1).split("&")) {
+        const eq = parameter.indexOf("=");
+        const name = eq === -1 ? parameter : parameter.slice(0, eq);
+        const value = eq === -1 ? "" : parameter.slice(eq + 1);
+        if ((name === "endpoint" || name === "grant") && value === "")
+            invalid(`the ${name} parameter has no value`);
+        if (name === "endpoint") {
+            const url = percentDecode(value, "an endpoint");
+            try {
+                checkReceivedUrl(url);
+            }
+            catch {
+                invalid("an endpoint is not a ws or wss URL (§16)");
+            }
+            endpoints.push(url);
+        }
+        else if (name === "grant") {
+            if (grant !== undefined)
+                invalid("the grant parameter appears twice");
+            grant = controlRecordId(id32(value, "the grant ID"));
+        }
+        else {
+            // Not defined by §18.2: ignored, but still a well-formed query parameter.
+            percentDecode(name, "a query parameter name");
+            percentDecode(value, "a query parameter value");
+        }
+    }
+    if (endpoints.length === 0)
+        invalid("the URI has no endpoint parameter");
+    if (grant === undefined)
+        invalid("the URI has no grant parameter");
+    let secret;
+    if (hash !== -1) {
+        const fragment = uri.slice(hash + 1);
+        if (!fragment.startsWith("secret="))
+            invalid("the fragment is not secret=<b64url>");
+        let bytes;
+        try {
+            bytes = fromBase64url(fragment.slice("secret=".length));
+        }
+        catch {
+            return invalid("the secret is not canonical unpadded base64url");
+        }
+        secret = decodeInviteSecret(bytes);
+    }
+    return Object.freeze({
+        resourceId: resource,
+        endpoints: Object.freeze(endpoints),
+        grantId: grant,
+        ...(secret !== undefined ? { secret } : {}),
+    });
+}
+//# sourceMappingURL=invite.js.map

package/dist/key-package.d.ts

@@ -0,0 +1,92 @@
+import { type DataEpoch, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type AgreementKeyPair, type ResourceDEK } from "@openlfcp/crypto";
+import { type Signer } from "./cose.js";
+import type { ControlView } from "./epoch.js";
+import { type KeyPackagePayload, type Parsed } from "./objects.js";
+import type { PrincipalDescriptor } from "./principal.js";
+/** §25.1: HPKE info = deterministic CBOR of ["LFCP-KEY-v1", resource_id, data_epoch, recipient]. */
+export declare function keyPackageHpkeInfo(resource: ResourceId, epoch: DataEpoch, recipient: PrincipalId): Uint8Array;
+/** §25.1: HPKE AAD = deterministic CBOR of [resource_id, data_epoch, control_head]. */
+export declare function keyPackageHpkeAad(resource: ResourceId, epoch: DataEpoch, controlHead: Uint8Array): Uint8Array;
+export type KeyPackageCheck = {
+    readonly kind: "authorized";
+    readonly sender: PrincipalDescriptor;
+} | {
+    readonly kind: "rejected";
+    readonly reason: "OTHER_RESOURCE" | "UNKNOWN_CONTROL_HEAD" | "UNKNOWN_EPOCH" | "UNKNOWN_SENDER" | "SIGNATURE" | "UNAUTHORIZED";
+    readonly wireCode: string;
+    readonly message: string;
+};
+/**
+ * The §25.2 checks of a received Key Package against the validated chain,
+ * all at the package's referenced Control Head:
+ *
+ * - the head is on the chain and the package's epoch is known there.
+ *   Packages of closed epochs stay valid (§25.2, G-EP6): they are needed
+ *   to read history. Otherwise MISSING_DEPENDENCY (§25.2, §26.3);
+ * - the sender resolves to a descriptor on the chain: MISSING_DEPENDENCY
+ *   (§10.5);
+ * - the package is signed by its sender (kid = sender): INVALID_SIGNATURE;
+ * - the sender held key/distribute and the recipient data/read, or an
+ *   active invite grant (canDistributeKey, LFCP-021): AUTHORIZATION_FAILED.
+ *
+ * Opening the package and checking the DEK commitment come after this.
+ */
+export declare function verifyKeyPackage(view: ControlView, parsed: Parsed<KeyPackagePayload>): KeyPackageCheck;
+/** The keys of the Principal a package is opened for: its descriptor and its X25519 key pair. */
+export interface KeyPackageRecipient {
+    readonly descriptor: PrincipalDescriptor;
+    readonly agreement: AgreementKeyPair;
+}
+export interface SealedKeyPackage {
+    /** The exact signed Key Package bytes. */
+    readonly bytes: Uint8Array;
+    /** §25: the §10.6 object ID of those bytes. */
+    readonly packageId: Hash32;
+}
+/**
+ * Creates a Key Package (§25): the DEK sealed with HPKE to the recipient's
+ * X25519 key, with the exact §25.1 info and AAD, in a payload signed by the
+ * sender. Sealing always uses a fresh ephemeral key. Whether the sender may
+ * distribute and the recipient may receive is checked by receivers
+ * (verifyKeyPackage); a sender can check it first with canDistributeKey.
+ */
+export declare function sealKeyPackage(options: {
+    readonly resourceId: ResourceId;
+    readonly epoch: DataEpoch;
+    /** The Control Head the package is authorized at. */
+    readonly controlHead: Uint8Array;
+    readonly recipient: PrincipalDescriptor;
+    readonly dek: ResourceDEK;
+    readonly signer: Signer;
+}): Promise<SealedKeyPackage>;
+/**
+ * Opens a Key Package for its named recipient and checks the DEK against
+ * the epoch's commitment (§25, §25.2). The caller passes the keys of the
+ * Principal the package names; there is no trying of other keys.
+ *
+ * Throws KEY_PACKAGE_RECIPIENT_MISMATCH (keys of another Principal),
+ * KEY_PACKAGE_OPEN_FAILED or DEK_COMMITMENT_MISMATCH. All are client-local:
+ * ignore the package and surface it (ADR 0001 N5).
+ */
+export declare function openKeyPackage(parsed: Parsed<KeyPackagePayload>, recipient: KeyPackageRecipient, expectedCommitment: Uint8Array): Promise<ResourceDEK>;
+export type ReceivedKeyPackage = {
+    readonly kind: "opened";
+    readonly dek: ResourceDEK;
+    readonly epoch: DataEpoch;
+} | Extract<KeyPackageCheck, {
+    kind: "rejected";
+}>
+/** Client-local (N5): ignore the package and surface it to the application. */
+ | {
+    readonly kind: "ignored";
+    readonly code: "KEY_PACKAGE_RECIPIENT_MISMATCH" | "KEY_PACKAGE_OPEN_FAILED" | "DEK_COMMITMENT_MISMATCH";
+    readonly message: string;
+};
+/**
+ * A received Key Package end to end: parse, the §25.2 checks at its head
+ * (verifyKeyPackage), then open it for `recipient` and check the DEK
+ * against the epoch's commitment from the chain.
+ */
+export declare function receiveKeyPackage(view: ControlView, bytes: Uint8Array, recipient: KeyPackageRecipient): Promise<ReceivedKeyPackage>;
+//# sourceMappingURL=key-package.d.ts.map

package/dist/key-package.js

@@ -0,0 +1,132 @@
+import { bytesEqual, dataEpoch, LfcpError, toHex, } from "@openlfcp/core";
+import { dekCommitment, openDek, sealDek, } from "@openlfcp/crypto";
+import { canDistributeKey } from "./capability.js";
+import { cborMap, encode } from "./cbor/index.js";
+import { signObject, verifySignedObject } from "./cose.js";
+import { expectedSignerOf, parseKeyPackage, } from "./objects.js";
+/**
+ * Key Packages (LFCP-WIRE-01 §25): HPKE delivery of a Resource DEK to one
+ * recipient Principal, signed by its sender.
+ *
+ * This module builds and receives packages: the exact §25.1 info and AAD,
+ * the §25.2 checks against the Control Chain, and sealing and opening
+ * through @openlfcp/crypto HPKE. Opening failures (the package does not open
+ * for its recipient, or its DEK does not match the commitment) are
+ * client-local: the package is ignored and surfaced; there is no wire code
+ * (ADR 0001 N5).
+ */
+const KEY_LABEL = "LFCP-KEY-v1";
+/** §25.1: HPKE info = deterministic CBOR of ["LFCP-KEY-v1", resource_id, data_epoch, recipient]. */
+export function keyPackageHpkeInfo(resource, epoch, recipient) {
+    return encode([KEY_LABEL, resource, dataEpoch(epoch), recipient]);
+}
+/** §25.1: HPKE AAD = deterministic CBOR of [resource_id, data_epoch, control_head]. */
+export function keyPackageHpkeAad(resource, epoch, controlHead) {
+    return encode([resource, dataEpoch(epoch), controlHead]);
+}
+const reject = (reason, wireCode, message) => Object.freeze({ kind: "rejected", reason, wireCode, message });
+/**
+ * The §25.2 checks of a received Key Package against the validated chain,
+ * all at the package's referenced Control Head:
+ *
+ * - the head is on the chain and the package's epoch is known there.
+ *   Packages of closed epochs stay valid (§25.2, G-EP6): they are needed
+ *   to read history. Otherwise MISSING_DEPENDENCY (§25.2, §26.3);
+ * - the sender resolves to a descriptor on the chain: MISSING_DEPENDENCY
+ *   (§10.5);
+ * - the package is signed by its sender (kid = sender): INVALID_SIGNATURE;
+ * - the sender held key/distribute and the recipient data/read, or an
+ *   active invite grant (canDistributeKey, LFCP-021): AUTHORIZATION_FAILED.
+ *
+ * Opening the package and checking the DEK commitment come after this.
+ */
+export function verifyKeyPackage(view, parsed) {
+    const p = parsed.payload;
+    if (!bytesEqual(p.resourceId, view.state.resourceId))
+        return reject("OTHER_RESOURCE", "MALFORMED_MESSAGE", "the package is for another Resource");
+    const atHead = view.stateAt(p.controlHead);
+    if (atHead === undefined)
+        return reject("UNKNOWN_CONTROL_HEAD", "MISSING_DEPENDENCY", `Control Head ${toHex(p.controlHead)} is not on the chain`);
+    if (!atHead.epochs.has(String(p.dataEpoch)))
+        return reject("UNKNOWN_EPOCH", "MISSING_DEPENDENCY", `epoch ${p.dataEpoch} is not known at the package's head`);
+    // §10.5: the sender resolves from the whole chain; whether it held
+    // key/distribute at the head is the authority check below.
+    const sender = view.state.principals.get(toHex(expectedSignerOf(p)));
+    if (sender === undefined)
+        return reject("UNKNOWN_SENDER", "MISSING_DEPENDENCY", "no Control Record describes the sender (§10.5)");
+    const signature = verifySignedObject(parsed.signed, sender);
+    if (!signature.valid)
+        return reject("SIGNATURE", "INVALID_SIGNATURE", `the package is not signed by its sender (${signature.reason})`);
+    const authority = canDistributeKey(atHead, p.sender, p.recipient, p.dataEpoch);
+    if (!authority.allowed)
+        return reject("UNAUTHORIZED", "AUTHORIZATION_FAILED", authority.reason);
+    return Object.freeze({ kind: "authorized", sender });
+}
+/**
+ * Creates a Key Package (§25): the DEK sealed with HPKE to the recipient's
+ * X25519 key, with the exact §25.1 info and AAD, in a payload signed by the
+ * sender. Sealing always uses a fresh ephemeral key. Whether the sender may
+ * distribute and the recipient may receive is checked by receivers
+ * (verifyKeyPackage); a sender can check it first with canDistributeKey.
+ */
+export async function sealKeyPackage(options) {
+    const epoch = dataEpoch(options.epoch);
+    const { enc, ciphertext } = await sealDek(options.recipient.x25519PublicKey, options.dek, keyPackageHpkeInfo(options.resourceId, epoch, options.recipient.principalId), keyPackageHpkeAad(options.resourceId, epoch, options.controlHead));
+    const payload = encode(cborMap([
+        [0, options.resourceId],
+        [1, epoch],
+        [2, options.recipient.principalId],
+        [3, options.controlHead],
+        [4, options.signer.descriptor.principalId],
+        [5, enc],
+        [6, ciphertext],
+    ]));
+    const signed = signObject(payload, options.signer);
+    return Object.freeze({ bytes: signed.bytes, packageId: signed.id });
+}
+/**
+ * Opens a Key Package for its named recipient and checks the DEK against
+ * the epoch's commitment (§25, §25.2). The caller passes the keys of the
+ * Principal the package names; there is no trying of other keys.
+ *
+ * Throws KEY_PACKAGE_RECIPIENT_MISMATCH (keys of another Principal),
+ * KEY_PACKAGE_OPEN_FAILED or DEK_COMMITMENT_MISMATCH. All are client-local:
+ * ignore the package and surface it (ADR 0001 N5).
+ */
+export async function openKeyPackage(parsed, recipient, expectedCommitment) {
+    const p = parsed.payload;
+    if (!bytesEqual(recipient.descriptor.principalId, p.recipient) ||
+        !bytesEqual(recipient.agreement.publicKey, recipient.descriptor.x25519PublicKey))
+        throw new LfcpError("KEY_PACKAGE_RECIPIENT_MISMATCH", "the keys given are not those of the package's recipient");
+    const dek = await openDek(recipient.agreement, p.hpkeEnc, p.hpkeCiphertext, keyPackageHpkeInfo(p.resourceId, p.dataEpoch, p.recipient), keyPackageHpkeAad(p.resourceId, p.dataEpoch, p.controlHead));
+    if (!bytesEqual(dekCommitment(p.resourceId, p.dataEpoch, dek), expectedCommitment))
+        throw new LfcpError("DEK_COMMITMENT_MISMATCH", "the opened DEK does not match the epoch's commitment");
+    return dek;
+}
+/**
+ * A received Key Package end to end: parse, the §25.2 checks at its head
+ * (verifyKeyPackage), then open it for `recipient` and check the DEK
+ * against the epoch's commitment from the chain.
+ */
+export async function receiveKeyPackage(view, bytes, recipient) {
+    const parsed = parseKeyPackage(bytes);
+    const check = verifyKeyPackage(view, parsed);
+    if (check.kind === "rejected")
+        return check;
+    const commitment = view.state.epochs.get(String(parsed.payload.dataEpoch))?.dekCommitment;
+    if (commitment === undefined)
+        return reject("UNKNOWN_EPOCH", "MISSING_DEPENDENCY", "the epoch has no known commitment");
+    try {
+        const dek = await openKeyPackage(parsed, recipient, commitment);
+        return Object.freeze({ kind: "opened", dek, epoch: parsed.payload.dataEpoch });
+    }
+    catch (e) {
+        if (e instanceof LfcpError &&
+            (e.code === "KEY_PACKAGE_RECIPIENT_MISMATCH" ||
+                e.code === "KEY_PACKAGE_OPEN_FAILED" ||
+                e.code === "DEK_COMMITMENT_MISMATCH"))
+            return Object.freeze({ kind: "ignored", code: e.code, message: e.message });
+        throw e;
+    }
+}
+//# sourceMappingURL=key-package.js.map