run402 4.69.8 → 4.70.0

package/sdk/dist/node/gitvault-handoff.js

@@ -1,17 +1,26 @@
 /**
- * gitvault — the Handoff Key (kygit-handoff design D3/D6/D10).
+ * gitvault — the Handoff Key and the Invite Key, one kind-parameterized
+ * module (kygit-handoff design D3/D6/D10; kygit-invite design D3).
  *
- * A Handoff Key is a bearer bridge, never a K_repo derivation of its own:
- * `kgh1_<base64url(handoff_id[16] || master_secret[32])>` (69 chars). Two
- * HKDF-SHA-256 derivations off `master_secret` (salt = the 16 raw
- * `handoff_id` bytes) produce `auth_secret` (what the gateway hashes and
- * compares) and `wrap_key` (what seals/opens the small envelope carrying
- * the vault's epoch key `k_e` directly — the gateway never sees either).
+ * Both keys are bearer bridges, never a K_repo derivation of their own:
+ * `kgh1_<base64url(handoff_id[16] || master_secret[32])>` /
+ * `kgi1_<base64url(invite_id[16] || master_secret[32])>` (69 chars each).
+ * Two HKDF-SHA-256 derivations off `master_secret` (salt = the 16 raw id
+ * bytes) produce `auth_secret` (what the gateway hashes and compares) and
+ * `wrap_key` (what seals/opens the small envelope carrying the vault's
+ * epoch key `k_e` directly — the gateway never sees either). The HKDF info
+ * strings and the auth-hash label are DOMAIN-SEPARATED by kind
+ * (`kygit/<kind>/auth/v1`, `kygit/<kind>/wrap/v1`,
+ * `kygit/<kind>/auth-hash/v1`) so a handoff-derived secret can never verify
+ * as an invite secret nor the reverse, even for a row whose id both parsers
+ * would recover.
  *
- * The prefix is a REGISTRY (design D9 rule 4): `kgh1_` is the first row.
- * `parseHandoffKey` refuses any other recognized-shape-but-wrong-kind
- * prefix BY NAME, pointing at its own verb, rather than misreading it as a
- * malformed handoff key.
+ * The prefix is a REGISTRY (design D9 rule 4 / kygit-invite D3): `kgh1_` is
+ * the first row, `kgi1_` the second. `parseClaimKey` refuses any other
+ * recognized-shape-but-wrong-kind prefix BY NAME, pointing at its own verb,
+ * rather than misreading it as a malformed key of the kind it expected.
+ * `parseHandoffKey`/`parseInviteKey` are thin kind-bound aliases over the
+ * one parser — every existing handoff export and test stays byte-identical.
  *
  * Reuses ONLY existing primitives — `jcs`/HKDF/HMAC/SHA-256 from
  * `@noble/hashes`, the SAME `_gitvaultAeadBackend()` XChaCha20-Poly1305
@@ -20,7 +29,10 @@
  * object frame (design D3: "the sealed envelope lives in the gateway ROW,
  * never in the vault object store — the frozen r402s/v0 protocol is
  * untouched"), so it gets its own tiny header/AAD rather than reusing
- * `frameAad`'s object-store-shaped seven fields.
+ * `frameAad`'s object-store-shaped seven fields. The invite envelope is a
+ * DIFFERENT, deliberately simpler format again than the `KGH1` handoff-
+ * bridge frame is from `r402s/v0` — same idea, one level down: `KGI1` is its
+ * own frame magic, never reused across kinds.
  */
 import { hkdf } from "@noble/hashes/hkdf.js";
 import { sha256 } from "@noble/hashes/sha2.js";
@@ -32,11 +44,20 @@ import { _gitvaultAeadBackend, fromBase64url, randomBytes, toBase64url, bytesToH
 function fail(code, message, context, details) {
     throw new LocalError(message, context, { code, details });
 }
-/** `kgh1_` is the first row. A future `kgi1_` (KyGit Invite) is a SIBLING row here, never a branch on this one's parser. */
-export const HANDOFF_KEY_PREFIXES = [{ prefix: "kgh1_", kind: "handoff", verb: "resume" }];
-const HANDOFF_ID_BYTES = 16;
+/**
+ * `kgh1_` is the first row (handoff); `kgi1_` is the second (invite,
+ * kygit-invite design D3). A future third kind is a SIBLING row here, never
+ * a branch on either existing one's parser.
+ */
+export const HANDOFF_KEY_PREFIXES = [
+    { prefix: "kgh1_", kind: "handoff", verb: "resume", errorPrefix: "HANDOFF", envelopeKind: "kygit-handoff-envelope-v2", noteSchema: "kygit.handoff-note.v1", frameMagic: "KGH1" },
+    { prefix: "kgi1_", kind: "invite", verb: "join", errorPrefix: "INVITE", envelopeKind: "kygit-invite-envelope-v2", noteSchema: "kygit.invite-note.v1", frameMagic: "KGI1" },
+];
+const HANDOFF_ENTRY = HANDOFF_KEY_PREFIXES[0];
+const INVITE_ENTRY = HANDOFF_KEY_PREFIXES[1];
+const CLAIM_ID_BYTES = 16;
 const MASTER_SECRET_BYTES = 32;
-const HANDOFF_KEY_BODY_BYTES = HANDOFF_ID_BYTES + MASTER_SECRET_BYTES;
+const CLAIM_KEY_BODY_BYTES = CLAIM_ID_BYTES + MASTER_SECRET_BYTES;
 function bytesToUuid(bytes) {
     const h = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
     return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
@@ -51,6 +72,14 @@ export function uuidToBytes(uuid, field = "handoff_id") {
         out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
     return out;
 }
+/** Assemble a printed claim key from a fresh 32-byte master secret and the gateway-minted claim id, for `entry`'s kind. */
+function assembleClaimKey(entry, claimId, masterSecret) {
+    if (masterSecret.length !== MASTER_SECRET_BYTES)
+        fail(`${entry.errorPrefix}_KEY_INVALID`, "master_secret must be 32 bytes", `assembling ${entry.kind} key`);
+    const idBytes = uuidToBytes(claimId, `${entry.kind}_id`);
+    const body = concatBytes(idBytes, masterSecret);
+    return { key: `${entry.prefix}${toBase64url(body)}`, id_bytes: idBytes, master_secret: masterSecret };
+}
 /**
  * Assemble the printed key from a fresh 32-byte master secret and the
  * gateway-minted `handoff_id`. The gateway never sees `master_secret` — the
@@ -58,64 +87,86 @@ export function uuidToBytes(uuid, field = "handoff_id") {
  * ONLY that.
  */
 export function assembleHandoffKey(handoffId, masterSecret = randomBytes(MASTER_SECRET_BYTES)) {
-    if (masterSecret.length !== MASTER_SECRET_BYTES)
-        fail("HANDOFF_KEY_INVALID", "master_secret must be 32 bytes", "assembling handoff key");
-    const idBytes = uuidToBytes(handoffId);
-    const body = concatBytes(idBytes, masterSecret);
-    return { key: `kgh1_${toBase64url(body)}`, handoff_id_bytes: idBytes, master_secret: masterSecret };
+    const { key, id_bytes, master_secret } = assembleClaimKey(HANDOFF_ENTRY, handoffId, masterSecret);
+    return { key, handoff_id_bytes: id_bytes, master_secret };
+}
+/** The invite-kind sibling of {@link assembleHandoffKey} (kygit-invite design D3). */
+export function assembleInviteKey(inviteId, masterSecret = randomBytes(MASTER_SECRET_BYTES)) {
+    const { key, id_bytes, master_secret } = assembleClaimKey(INVITE_ENTRY, inviteId, masterSecret);
+    return { key, invite_id_bytes: id_bytes, master_secret };
 }
 /**
- * Parse ANY `kg**_` handoff-family key by its prefix registry. A recognized
- * prefix of a DIFFERENT kind (a future `kgi1_` invite key handed to
- * `resume`) refuses BY NAME pointing at its own verb — never misread as a
- * malformed handoff key (design D9 rule 4).
+ * Parse ANY `kg**_` claim-family key by its prefix registry against the
+ * `expectedKind` the calling verb accepts. A recognized prefix of a
+ * DIFFERENT kind (a `kgi1_` invite key handed to `resume`, or a `kgh1_`
+ * handoff key handed to `join`) refuses BY NAME pointing at its own verb —
+ * never misread as a malformed key of the expected kind, and never
+ * contacting the gateway (design D9 rule 4 / kygit-invite design D3).
  */
-export function parseHandoffKey(raw) {
+export function parseClaimKey(raw, expectedKind) {
+    const expectedEntry = expectedKind === "handoff" ? HANDOFF_ENTRY : INVITE_ENTRY;
     const trimmed = raw.trim();
     const entry = HANDOFF_KEY_PREFIXES.find((e) => trimmed.startsWith(e.prefix));
     if (!entry) {
-        // A recognized SIBLING prefix (future kind) would be matched here once
-        // it joins the registry; today only `kgh1_` is registered, so any
-        // non-matching prefix is a plain invalid key.
-        fail("HANDOFF_KEY_INVALID", "not a recognized kygit key (expected a key starting kgh1_)", "parsing handoff key");
+        fail(`${expectedEntry.errorPrefix}_KEY_INVALID`, `not a recognized kygit key (expected a key starting ${expectedEntry.prefix})`, "parsing claim key");
     }
-    if (entry.kind !== "handoff") {
-        fail("HANDOFF_KEY_WRONG_KIND", `this key is a ${entry.kind} key — use \`kygit ${entry.verb}\` instead of resume`, "parsing handoff key", { kind: entry.kind, verb: entry.verb });
+    if (entry.kind !== expectedKind) {
+        fail(`${expectedEntry.errorPrefix}_KEY_WRONG_KIND`, `this key is a ${entry.kind} key — use \`kygit ${entry.verb}\` instead of ${expectedEntry.verb}`, "parsing claim key", { kind: entry.kind, verb: entry.verb });
     }
     const body = trimmed.slice(entry.prefix.length);
     let bytes;
     try {
-        bytes = fromBase64url(body, "handoff key body");
+        bytes = fromBase64url(body, `${entry.kind} key body`);
     }
     catch {
-        fail("HANDOFF_KEY_INVALID", "the key body is not valid base64url", "parsing handoff key");
+        fail(`${entry.errorPrefix}_KEY_INVALID`, "the key body is not valid base64url", "parsing claim key");
     }
-    if (bytes.length !== HANDOFF_KEY_BODY_BYTES) {
-        fail("HANDOFF_KEY_INVALID", `the key decodes to ${bytes.length} bytes; expected ${HANDOFF_KEY_BODY_BYTES}`, "parsing handoff key");
+    if (bytes.length !== CLAIM_KEY_BODY_BYTES) {
+        fail(`${entry.errorPrefix}_KEY_INVALID`, `the key decodes to ${bytes.length} bytes; expected ${CLAIM_KEY_BODY_BYTES}`, "parsing claim key");
     }
-    const idBytes = bytes.subarray(0, HANDOFF_ID_BYTES);
-    const masterSecret = bytes.subarray(HANDOFF_ID_BYTES);
-    return { kind: "handoff", handoff_id_bytes: idBytes, handoff_id: bytesToUuid(idBytes), master_secret: masterSecret };
+    const idBytes = bytes.subarray(0, CLAIM_ID_BYTES);
+    const masterSecret = bytes.subarray(CLAIM_ID_BYTES);
+    return { kind: entry.kind, id_bytes: idBytes, id: bytesToUuid(idBytes), master_secret: masterSecret };
 }
-// ─── HKDF derivations (design D3) ────────────────────────────────────────────
-const HANDOFF_AUTH_INFO = "kygit/handoff/auth/v1";
-const HANDOFF_WRAP_INFO = "kygit/handoff/wrap/v1";
-const HANDOFF_AUTH_HASH_LABEL = "kygit/handoff/auth-hash/v1";
-/** `HKDF-SHA256(ikm=master_secret, salt=handoff_id[16], info=…)` per D3, for both `auth_secret` and `wrap_key`. */
-export function deriveHandoffSecrets(handoffIdBytes, masterSecret) {
-    const authSecret = hkdf(sha256, masterSecret, handoffIdBytes, utf8ToBytes(HANDOFF_AUTH_INFO), 32);
-    const wrapKey = hkdf(sha256, masterSecret, handoffIdBytes, utf8ToBytes(HANDOFF_WRAP_INFO), 32);
+/**
+ * Parse ANY `kg**_` handoff-family key by its prefix registry. A recognized
+ * prefix of a DIFFERENT kind (an invite key handed to `resume`) refuses BY
+ * NAME pointing at its own verb — never misread as a malformed handoff key
+ * (design D9 rule 4). Kind-bound alias of {@link parseClaimKey}.
+ */
+export function parseHandoffKey(raw) {
+    const parsed = parseClaimKey(raw, "handoff");
+    return { kind: "handoff", handoff_id_bytes: parsed.id_bytes, handoff_id: parsed.id, master_secret: parsed.master_secret };
+}
+/** The invite-kind sibling of {@link parseHandoffKey} (kygit-invite design D3). */
+export function parseInviteKey(raw) {
+    const parsed = parseClaimKey(raw, "invite");
+    return { kind: "invite", invite_id_bytes: parsed.id_bytes, invite_id: parsed.id, master_secret: parsed.master_secret };
+}
+/** `HKDF-SHA256(ikm=master_secret, salt=id[16], info=…)` per D3, domain-separated by kind, for both `auth_secret` and `wrap_key`. */
+function deriveClaimSecrets(kind, idBytes, masterSecret) {
+    const authInfo = `kygit/${kind}/auth/v1`;
+    const wrapInfo = `kygit/${kind}/wrap/v1`;
+    const authHashLabel = `kygit/${kind}/auth-hash/v1`;
+    const authSecret = hkdf(sha256, masterSecret, idBytes, utf8ToBytes(authInfo), 32);
+    const wrapKey = hkdf(sha256, masterSecret, idBytes, utf8ToBytes(wrapInfo), 32);
+    const authHash = sha256(concatBytes(utf8ToBytes(authHashLabel), authSecret));
     // ONE SHA-256 over (label ‖ auth_secret), hex-encoded — exactly what the
     // gateway recomputes at claim (`computeAuthHash`). Through 4.68.1 this line
     // ran the digest through `sha256Hex` (which hashes its input again), so the
     // stored value was sha256(sha256(label ‖ secret)) and NO key minted by any
-    // published client could ever verify — the mint/claim agreement test above
-    // compared two calls of this same function and could not see it. The
-    // cross-side vector in gitvault-handoff.test.ts now recomputes the
-    // gateway's hash independently.
-    const authHash = sha256(concatBytes(utf8ToBytes(HANDOFF_AUTH_HASH_LABEL), authSecret));
+    // published client could ever verify. The cross-side vector in
+    // gitvault-handoff.test.ts now recomputes the gateway's hash independently.
     return { auth_secret: authSecret, wrap_key: wrapKey, auth_hash_hex: bytesToHex(authHash) };
 }
+/** `HKDF-SHA256(ikm=master_secret, salt=handoff_id[16], info=kygit/handoff/…)` per D3, for both `auth_secret` and `wrap_key`. */
+export function deriveHandoffSecrets(handoffIdBytes, masterSecret) {
+    return deriveClaimSecrets("handoff", handoffIdBytes, masterSecret);
+}
+/** The invite-kind sibling of {@link deriveHandoffSecrets}, domain-separated under `kygit/invite/…` info strings (kygit-invite design D3) — an invite secret never verifies as a handoff hash, or the reverse. */
+export function deriveInviteSecrets(inviteIdBytes, masterSecret) {
+    return deriveClaimSecrets("invite", inviteIdBytes, masterSecret);
+}
 // ─── Writer-admission grant + acceptance (gitvault-multi-writer D4/§4.17) ───
 //
 // The bearer-completable path for `add_writer_key{authorization.kind:
@@ -131,17 +182,27 @@ export function deriveHandoffSecrets(handoffIdBytes, masterSecret) {
 // JCS(statement)` — that text is stale; the shipped gateway code calls its
 // own `signaturePreimage("handoff-writer-accept/v1", acceptance.statement)`,
 // the identical convention used here).
-const HANDOFF_WRITER_ADMISSION_INFO = "kygit/handoff/writer-admission/v1";
 /**
- * Third HKDF output of the Handoff Key's `master_secret` (design D4,
- * protocol §4.17): the one-use admission Ed25519 seed. Derived directly
- * from `master_secret` — deliberately NEVER from `auth_secret` or
- * `wrap_key` — so the gateway, which receives `auth_secret` at claim, stays
- * computationally unable to derive this seed and manufacture a different
- * claimant completion.
+ * Third HKDF output of a claim key's `master_secret` (design D4, protocol
+ * §4.17; kind-parameterized by kygit-invite design D3): the one-use
+ * admission Ed25519 seed. Derived directly from `master_secret` —
+ * deliberately NEVER from `auth_secret` or `wrap_key` — so the gateway,
+ * which receives `auth_secret` at claim, stays computationally unable to
+ * derive this seed and manufacture a different claimant completion. The info
+ * string is domain-separated by kind (`kygit/<kind>/writer-admission/v1`),
+ * so an invite's admission seed never matches a handoff's for the same id
+ * and master secret.
  */
+export function deriveClaimWriterAdmissionSeed(kind, idBytes, masterSecret) {
+    return hkdf(sha256, masterSecret, idBytes, utf8ToBytes(`kygit/${kind}/writer-admission/v1`), 32);
+}
+/** Handoff-bound alias of {@link deriveClaimWriterAdmissionSeed} — `kygit/handoff/writer-admission/v1`. */
 export function deriveWriterAdmissionSeed(handoffIdBytes, masterSecret) {
-    return hkdf(sha256, masterSecret, handoffIdBytes, utf8ToBytes(HANDOFF_WRITER_ADMISSION_INFO), 32);
+    return deriveClaimWriterAdmissionSeed("handoff", handoffIdBytes, masterSecret);
+}
+/** The invite-kind sibling of {@link deriveWriterAdmissionSeed} — `kygit/invite/writer-admission/v1` (kygit-invite design D3). */
+export function deriveInviteWriterAdmissionSeed(inviteIdBytes, masterSecret) {
+    return deriveClaimWriterAdmissionSeed("invite", inviteIdBytes, masterSecret);
 }
 const WRITER_MINTED_ROLES = ["owner", "admin", "developer", "billing", "viewer"];
 /** Mint side (D4): builds + signs `writer_admission_grant`. The gateway's own mint-time validation (grantor active + self-consistent, field equality) is server-side; this function only builds a well-formed, correctly-signed object. */
@@ -251,20 +312,19 @@ export function verifyWriterAcceptance(acceptance, admissionPubkeyRaw) {
     const preimage = signaturePreimage(HANDOFF_WRITER_ACCEPT_PREIMAGE_DOMAIN, acceptance.statement);
     return ed25519VerifyStrict(acceptanceSig, preimage, admissionPubkeyRaw) && ed25519VerifyStrict(possessionSig, preimage, signingPubkey);
 }
-/** Frame tag for this envelope format — DISTINCT from `r402s/v0`'s `"R402S0"` object frame (design D3: never stored as a vault object). */
+/** Frame tag for the handoff envelope format — DISTINCT from `r402s/v0`'s `"R402S0"` object frame (design D3: never stored as a vault object). The LEGACY v1 tag: nothing seals it any more, but a pre-gitvault-multi-writer handoff row still carries one and {@link openHandoffEnvelope} still opens it. */
 export const HANDOFF_ENVELOPE_KIND = "kygit-handoff-envelope-v1";
-const HANDOFF_FRAME_MAGIC = "KGH1";
-const HANDOFF_FRAME_MAGIC_BYTES = 4;
-const HANDOFF_FRAME_VERSION_BYTE = 0x01;
-const HANDOFF_NONCE_BYTES = 24;
-const HANDOFF_FRAME_HEADER_BYTES = HANDOFF_FRAME_MAGIC_BYTES + 1 + HANDOFF_NONCE_BYTES;
-function handoffAeadSeal(key32, nonce24, aad, plaintext) {
+const FRAME_MAGIC_BYTES = 4;
+const FRAME_VERSION_BYTE = 0x01;
+const CLAIM_NONCE_BYTES = 24;
+const CLAIM_FRAME_HEADER_BYTES = FRAME_MAGIC_BYTES + 1 + CLAIM_NONCE_BYTES;
+function claimAeadSeal(key32, nonce24, aad, plaintext) {
     const backend = _gitvaultAeadBackend();
     if (backend)
         return backend.seal(key32, nonce24, aad, plaintext);
     return xchacha20poly1305(key32, nonce24, aad).encrypt(plaintext);
 }
-function handoffAeadOpen(key32, nonce24, aad, ctAndTag) {
+function claimAeadOpen(key32, nonce24, aad, ctAndTag) {
     try {
         const backend = _gitvaultAeadBackend();
         if (backend)
@@ -275,9 +335,9 @@ function handoffAeadOpen(key32, nonce24, aad, ctAndTag) {
         return null;
     }
 }
-/** AAD = `handoff_id[16] ‖ kind` (design D3) — `kind` is this envelope format's own tag, UTF-8. */
-function handoffEnvelopeAad(handoffIdBytes, envelopeKind) {
-    return concatBytes(handoffIdBytes, utf8ToBytes(envelopeKind));
+/** AAD = `id[16] ‖ envelopeKind` (design D3) — `envelopeKind` is this envelope format's own tag, UTF-8. */
+function claimEnvelopeAad(idBytes, envelopeKind) {
+    return concatBytes(idBytes, utf8ToBytes(envelopeKind));
 }
 /**
  * `sealed_envelope` on the wire is STANDARD base64 — openapi spells it
@@ -285,11 +345,14 @@ function handoffEnvelopeAad(handoffIdBytes, envelopeKind) {
  * gateway echoes the stored bytes with `Buffer#toString("base64")` (`+`,
  * `/`, `=` padding). Decoding it with the canonical-base64url-only
  * `fromBase64url`, which refuses every `+`/`/`/`=`, takes a 200 from the
- * gateway and dies client-side with HANDOFF_ENVELOPE_INVALID. This decoder
+ * gateway and dies client-side with `*_ENVELOPE_INVALID`. This decoder
  * reads the documented form and, for tolerance, the base64url form other
- * clients mint; padding is optional either way. Anything
- * outside the two alphabets is a refusal (`null` — the caller raises the
- * typed HANDOFF_ENVELOPE_INVALID), never a silent partial decode.
+ * clients mint; padding is optional either way. Anything outside the two
+ * alphabets is a refusal (`null` — the caller raises the typed
+ * `*_ENVELOPE_INVALID`), never a silent partial decode. Shared by both
+ * claim kinds: the invite routes encode exactly as the handoff routes do,
+ * byte for byte, rather than "fixing" the alphabet on one side only
+ * (kygit-invite design D3's cross-side trap).
  */
 function decodeSealedEnvelope(value) {
     const trimmed = value.trim();
@@ -305,91 +368,107 @@ function decodeSealedEnvelope(value) {
         return null;
     }
 }
-// Plain JSON, NOT the r402s/v0 no-JSON-numbers JCS profile: this envelope is
-// never a vault object and only this SDK ever encodes/decodes it, so it
-// needs deterministic round-tripping, not cross-implementation
-// byte-canonical determinism (design D3's "the frozen protocol is
-// untouched" — reusing the object-frame profile here would be exactly the
-// kind of accidental protocol coupling that note warns against). Shared by
-// every envelope kind (v1, v2, …) so the frame byte-layout lives in exactly
-// one place — a v1/v2 divergence here would be invisible to either side
-// until a cross-version open failed.
-function sealHandoffEnvelopeFrame(handoffIdBytes, wrapKey, payload, envelopeKind, nonce) {
+/**
+ * Seal `payload` under `wrap_key` for `entry`'s kind, tagged `envelopeKind`.
+ * Returns the standard-base64 wire form (openapi `format: byte`) + the tag.
+ *
+ * Plain JSON, NOT the r402s/v0 no-JSON-numbers JCS profile: this envelope is
+ * never a vault object and only this SDK ever encodes/decodes it, so it
+ * needs deterministic round-tripping, not cross-implementation
+ * byte-canonical determinism (design D3's "the frozen protocol is
+ * untouched" — reusing the object-frame profile here would be exactly the
+ * kind of accidental protocol coupling that note warns against). Shared by
+ * every claim kind and every envelope version (v1, v2, …) so the frame
+ * byte-layout lives in exactly one place — a kind or version divergence here
+ * would be invisible to either side until a cross-open failed.
+ */
+function sealClaimEnvelope(entry, idBytes, wrapKey, payload, envelopeKind, nonce) {
     const plaintext = utf8ToBytes(JSON.stringify(payload));
-    const n = nonce ?? randomBytes(HANDOFF_NONCE_BYTES);
-    if (n.length !== HANDOFF_NONCE_BYTES)
-        fail("HANDOFF_ENVELOPE_INVALID", "nonce must be 24 bytes", "sealing handoff envelope");
-    const aad = handoffEnvelopeAad(handoffIdBytes, envelopeKind);
-    const ct = handoffAeadSeal(wrapKey, n, aad, plaintext);
-    const frame = concatBytes(utf8ToBytes(HANDOFF_FRAME_MAGIC), new Uint8Array([HANDOFF_FRAME_VERSION_BYTE]), n, ct);
+    const n = nonce ?? randomBytes(CLAIM_NONCE_BYTES);
+    if (n.length !== CLAIM_NONCE_BYTES)
+        fail(`${entry.errorPrefix}_ENVELOPE_INVALID`, "nonce must be 24 bytes", `sealing ${entry.kind} envelope`);
+    const aad = claimEnvelopeAad(idBytes, envelopeKind);
+    const ct = claimAeadSeal(wrapKey, n, aad, plaintext);
+    const frame = concatBytes(utf8ToBytes(entry.frameMagic), new Uint8Array([FRAME_VERSION_BYTE]), n, ct);
     return { sealed_envelope: base64.encode(frame), envelope_kind: envelopeKind };
 }
-/** Seal the handoff payload under `wrap_key`. Returns the standard-base64 wire form (openapi `format: byte`) + its declared kind tag. */
-export function sealHandoffEnvelope(handoffIdBytes, wrapKey, payload, nonce) {
-    return sealHandoffEnvelopeFrame(handoffIdBytes, wrapKey, payload, HANDOFF_ENVELOPE_KIND, nonce);
-}
 /**
- * Decodes, header-checks, AEAD-opens, and JSON-parses a sealed envelope,
- * returning the RAW parsed payload with no shape validation — shared by
- * every envelope kind (mirrors {@link sealHandoffEnvelopeFrame} on the seal
- * side) so the frame byte-layout lives in exactly one place. Each envelope
- * kind's own `open*` function applies its OWN shape check on the result;
- * this function deliberately does not, since a shape check IS the version
- * discriminator (a v1 opener must reject a `v:2` payload, not silently
- * accept it — that is what makes `v` meaningful at all).
+ * Decodes, header-checks, AEAD-opens, and JSON-parses a sealed envelope for
+ * `entry`'s kind, returning the RAW parsed payload with no shape validation
+ * (mirrors {@link sealClaimEnvelope} on the seal side) so the frame
+ * byte-layout lives in exactly one place. Each envelope kind/version's own
+ * `open*` function applies its OWN shape check on the result; this function
+ * deliberately does not, since a shape check IS the version discriminator (a
+ * v1 opener must reject a `v:2` payload, not silently accept it — that is
+ * what makes `v` meaningful at all). Throws `${errorPrefix}_ENVELOPE_INVALID`
+ * on any header mismatch and `${errorPrefix}_AEAD_AUTH_FAILURE` on a bad
+ * key/AAD/ciphertext.
  */
-function openHandoffEnvelopeFrame(handoffIdBytes, wrapKey, sealedEnvelope, envelopeKind) {
+function openClaimEnvelope(entry, idBytes, wrapKey, sealedEnvelope, envelopeKind) {
     const frame = decodeSealedEnvelope(sealedEnvelope);
     if (frame === null) {
-        fail("HANDOFF_ENVELOPE_INVALID", "sealed_envelope is not valid base64", "opening handoff envelope");
+        fail(`${entry.errorPrefix}_ENVELOPE_INVALID`, "sealed_envelope is not valid base64", `opening ${entry.kind} envelope`);
     }
-    if (frame.length < HANDOFF_FRAME_HEADER_BYTES + 16) {
-        fail("HANDOFF_ENVELOPE_INVALID", "sealed_envelope is shorter than header + AEAD tag", "opening handoff envelope");
+    if (frame.length < CLAIM_FRAME_HEADER_BYTES + 16) {
+        fail(`${entry.errorPrefix}_ENVELOPE_INVALID`, "sealed_envelope is shorter than header + AEAD tag", `opening ${entry.kind} envelope`);
     }
-    const magic = new TextDecoder().decode(frame.subarray(0, HANDOFF_FRAME_MAGIC_BYTES));
-    if (magic !== HANDOFF_FRAME_MAGIC || frame[HANDOFF_FRAME_MAGIC_BYTES] !== HANDOFF_FRAME_VERSION_BYTE) {
-        fail("HANDOFF_ENVELOPE_INVALID", "sealed_envelope header magic/version mismatch", "opening handoff envelope");
+    const magic = new TextDecoder().decode(frame.subarray(0, FRAME_MAGIC_BYTES));
+    if (magic !== entry.frameMagic || frame[FRAME_MAGIC_BYTES] !== FRAME_VERSION_BYTE) {
+        fail(`${entry.errorPrefix}_ENVELOPE_INVALID`, "sealed_envelope header magic/version mismatch", `opening ${entry.kind} envelope`);
     }
-    const nonce = frame.subarray(HANDOFF_FRAME_MAGIC_BYTES + 1, HANDOFF_FRAME_HEADER_BYTES);
-    const ct = frame.subarray(HANDOFF_FRAME_HEADER_BYTES);
-    const aad = handoffEnvelopeAad(handoffIdBytes, envelopeKind);
-    const opened = handoffAeadOpen(wrapKey, nonce, aad, ct);
+    const nonce = frame.subarray(FRAME_MAGIC_BYTES + 1, CLAIM_FRAME_HEADER_BYTES);
+    const ct = frame.subarray(CLAIM_FRAME_HEADER_BYTES);
+    const aad = claimEnvelopeAad(idBytes, envelopeKind);
+    const opened = claimAeadOpen(wrapKey, nonce, aad, ct);
     if (opened === null)
-        fail("HANDOFF_AEAD_AUTH_FAILURE", "the sealed envelope failed AEAD authentication under this key", "opening handoff envelope");
+        fail(`${entry.errorPrefix}_AEAD_AUTH_FAILURE`, "the sealed envelope failed AEAD authentication under this key", `opening ${entry.kind} envelope`);
     try {
         return JSON.parse(new TextDecoder().decode(opened));
     }
     catch {
-        fail("HANDOFF_ENVELOPE_INVALID", "opened envelope is not valid JSON", "opening handoff envelope");
+        fail(`${entry.errorPrefix}_ENVELOPE_INVALID`, "opened envelope is not valid JSON", `opening ${entry.kind} envelope`);
     }
 }
+/** Seal the handoff payload under `wrap_key` as a LEGACY v1 envelope. Returns the standard-base64 wire form (openapi `format: byte`) + its declared kind tag. Nothing in the shipped flow calls this any more — {@link sealHandoffEnvelopeV2} is what `handoff` seals — but the v1 shape stays openable and sealable for the conformance vectors. */
+export function sealHandoffEnvelope(handoffIdBytes, wrapKey, payload, nonce) {
+    return sealClaimEnvelope(HANDOFF_ENTRY, handoffIdBytes, wrapKey, payload, HANDOFF_ENVELOPE_KIND, nonce);
+}
 /** Open a sealed handoff envelope under `wrap_key` (standard base64 as the claim response carries it, or base64url). Throws `HANDOFF_ENVELOPE_INVALID` on any header mismatch, a `v:2` (or otherwise non-v1) payload shape, and `HANDOFF_AEAD_AUTH_FAILURE` on a bad key/AAD/ciphertext. */
 export function openHandoffEnvelope(handoffIdBytes, wrapKey, sealedEnvelope, envelopeKind = HANDOFF_ENVELOPE_KIND) {
-    const payload = openHandoffEnvelopeFrame(handoffIdBytes, wrapKey, sealedEnvelope, envelopeKind);
-    const p = payload;
+    const p = openClaimEnvelope(HANDOFF_ENTRY, handoffIdBytes, wrapKey, sealedEnvelope, envelopeKind);
     if (p.v !== 1 || p.kind !== "handoff" || typeof p.repo_id !== "string" || typeof p.epoch !== "string" || typeof p.k_e_hex !== "string" || !p.checkpoint || p.note_schema !== "kygit.handoff-note.v1") {
         fail("HANDOFF_ENVELOPE_INVALID", "opened envelope does not match the kygit.handoff-note.v1 payload shape", "opening handoff envelope");
     }
     return p;
 }
-// ─── Envelope v2 (gitvault-multi-writer D4/§4.17) ────────────────────────────
-/**
- * `kygit-handoff-envelope-v2` adds `writer_admission_grant_sha256` to the
- * v1 payload — design D4's "no hash cycle: grant first, then seal": the
- * minter builds + signs {@link WriterAdmissionGrant} FIRST, hashes its
- * stored bytes SECOND, and only THEN seals this envelope carrying that
- * hash. The claimant cross-checks it against the grant the gateway
- * independently returns at claim, an integrity binding entirely
- * independent of anything the gateway could tamper with (the envelope's
- * AEAD authenticity comes from `wrap_key`, which the gateway never holds).
- */
+// ─── Envelope v2 (gitvault-multi-writer D4/§4.17; kygit-invite design D3) ───
+//
+// `writer_admission_grant_sha256` is what makes v2 v2 — design D4's "no hash
+// cycle: grant first, then seal": the minter builds + signs
+// {@link WriterAdmissionGrant} FIRST, hashes its stored bytes SECOND, and
+// only THEN seals this envelope carrying that hash. The claimant
+// cross-checks it against the grant the gateway independently returns at
+// claim, an integrity binding entirely independent of anything the gateway
+// could tamper with (the envelope's AEAD authenticity comes from `wrap_key`,
+// which the gateway never holds). BOTH claim kinds seal v2 — an invite has
+// no v1 at all, and a handoff's v1 survives only as a legacy opener.
+/** The v2 envelope kind the handoff mint seals. */
 export const HANDOFF_ENVELOPE_V2_KIND = "kygit-handoff-envelope-v2";
-/** Seal a v2 envelope — identical framing to {@link sealHandoffEnvelope}, tagged `kygit-handoff-envelope-v2` so its AAD (and therefore its ciphertext) is never confusable with a v1 envelope of the same handoff. */
+/** The v2 envelope kind the invite mint seals (kygit-invite design D3) — its own tag, never confusable with the handoff one even for the same id. */
+export const INVITE_ENVELOPE_V2_KIND = "kygit-invite-envelope-v2";
+/** Seal a v2 handoff envelope — identical framing to {@link sealHandoffEnvelope}, tagged `kygit-handoff-envelope-v2` so its AAD (and therefore its ciphertext) is never confusable with a v1 envelope of the same handoff. */
 export function sealHandoffEnvelopeV2(handoffIdBytes, wrapKey, payload, nonce) {
     if (!GITVAULT_SHA256_RE.test(payload.writer_admission_grant_sha256)) {
         fail("VALIDATION_FAILED", "writer_admission_grant_sha256 must be 64 lowercase hex", "sealing handoff envelope v2", { field: "writer_admission_grant_sha256" });
     }
-    return sealHandoffEnvelopeFrame(handoffIdBytes, wrapKey, payload, HANDOFF_ENVELOPE_V2_KIND, nonce);
+    return sealClaimEnvelope(HANDOFF_ENTRY, handoffIdBytes, wrapKey, payload, HANDOFF_ENVELOPE_V2_KIND, nonce);
+}
+/** The invite-kind sibling of {@link sealHandoffEnvelopeV2} — the ONLY invite envelope there is (kygit-invite design D3). */
+export function sealInviteEnvelope(inviteIdBytes, wrapKey, payload, nonce) {
+    if (!GITVAULT_SHA256_RE.test(payload.writer_admission_grant_sha256)) {
+        fail("VALIDATION_FAILED", "writer_admission_grant_sha256 must be 64 lowercase hex", "sealing invite envelope", { field: "writer_admission_grant_sha256" });
+    }
+    return sealClaimEnvelope(INVITE_ENTRY, inviteIdBytes, wrapKey, payload, INVITE_ENVELOPE_V2_KIND, nonce);
 }
 /**
  * Open a v2 envelope for a writer-activation flow. Refuses a v1 (or any
@@ -398,7 +477,7 @@ export function sealHandoffEnvelopeV2(handoffIdBytes, wrapKey, payload, nonce) {
  * writer-activation-aware `resume` needs `writer_admission_grant_sha256` to
  * cross-check the returned grant, and a pre-rev-47 v1 envelope structurally
  * has none. Shares ONLY the frame/AEAD-opening step with
- * {@link openHandoffEnvelope} ({@link openHandoffEnvelopeFrame}) — NOT that
+ * {@link openHandoffEnvelope} ({@link openClaimEnvelope}) — NOT that
  * function itself, since its `v !== 1` shape check would (correctly) refuse
  * a v2 payload; this function applies its own `v !== 2` shape check
  * instead. Callers that only need K_repo/checkpoint delivery, with no
@@ -410,8 +489,7 @@ export function openHandoffEnvelopeV2(handoffIdBytes, wrapKey, sealedEnvelope, e
     if (envelopeKind !== HANDOFF_ENVELOPE_V2_KIND) {
         fail("HANDOFF_ENVELOPE_UNSUPPORTED", `this handoff's envelope is ${envelopeKind ? `\`${envelopeKind}\`` : "of an unrecognized kind"}, not \`${HANDOFF_ENVELOPE_V2_KIND}\` — writer activation needs the v2 envelope's writer_admission_grant_sha256, which a pre-gitvault-multi-writer handoff never carries`, "opening handoff envelope for writer activation", { received: envelopeKind, required: HANDOFF_ENVELOPE_V2_KIND });
     }
-    const payload = openHandoffEnvelopeFrame(handoffIdBytes, wrapKey, sealedEnvelope, envelopeKind);
-    const p = payload;
+    const p = openClaimEnvelope(HANDOFF_ENTRY, handoffIdBytes, wrapKey, sealedEnvelope, envelopeKind);
     if (p.v !== 2 ||
         p.kind !== "handoff" ||
         typeof p.repo_id !== "string" ||
@@ -425,12 +503,37 @@ export function openHandoffEnvelopeV2(handoffIdBytes, wrapKey, sealedEnvelope, e
     }
     return p;
 }
+/** The invite-kind sibling of {@link openHandoffEnvelopeV2} — throws `INVITE_ENVELOPE_UNSUPPORTED` / `INVITE_ENVELOPE_INVALID` / `INVITE_AEAD_AUTH_FAILURE` (kygit-invite design D3). */
+export function openInviteEnvelope(inviteIdBytes, wrapKey, sealedEnvelope, envelopeKind = INVITE_ENVELOPE_V2_KIND) {
+    if (envelopeKind !== INVITE_ENVELOPE_V2_KIND) {
+        fail("INVITE_ENVELOPE_UNSUPPORTED", `this invite's envelope is ${envelopeKind ? `\`${envelopeKind}\`` : "of an unrecognized kind"}, not \`${INVITE_ENVELOPE_V2_KIND}\``, "opening invite envelope", { received: envelopeKind, required: INVITE_ENVELOPE_V2_KIND });
+    }
+    const p = openClaimEnvelope(INVITE_ENTRY, inviteIdBytes, wrapKey, sealedEnvelope, envelopeKind);
+    if (p.v !== 2 ||
+        p.kind !== "invite" ||
+        typeof p.repo_id !== "string" ||
+        typeof p.epoch !== "string" ||
+        typeof p.k_e_hex !== "string" ||
+        !p.checkpoint ||
+        p.note_schema !== "kygit.invite-note.v1" ||
+        typeof p.writer_admission_grant_sha256 !== "string" ||
+        !GITVAULT_SHA256_RE.test(p.writer_admission_grant_sha256)) {
+        fail("INVITE_ENVELOPE_INVALID", "opened envelope does not match the v2 kygit.invite-note.v1 payload shape", "opening invite envelope");
+    }
+    return p;
+}
 export function isKygitHandoffNote(value) {
     if (!value || typeof value !== "object")
         return false;
     const v = value;
     return v.schema === "kygit.handoff-note.v1" && typeof v.summary === "string" && typeof v.created_at === "string" && !!v.from && !!v.capture;
 }
+export function isKygitInviteNote(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return v.schema === "kygit.invite-note.v1" && typeof v.summary === "string" && typeof v.created_at === "string" && !!v.from && !!v.capture;
+}
 // ─── Client-side secret scan (design D10 — no override flag) ────────────────
 const HANDOFF_NOTE_SECRET_PREFIXES = [
     /\bsk-[A-Za-z0-9]/,
@@ -441,6 +544,10 @@ const HANDOFF_NOTE_SECRET_PREFIXES = [
     /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
     /-----BEGIN [A-Z ]*CERTIFICATE-----/,
     /\bkgh1_[A-Za-z0-9_-]/,
+    // kygit-invite design D3: the invite key joins the scan's known-prefix
+    // list so a pasted kgi1_ reads as a bare secret in EITHER note kind, not
+    // just its own.
+    /\bkgi1_[A-Za-z0-9_-]/,
 ];
 /** Shannon entropy in bits/char over `s`. */
 function shannonEntropy(s) {
@@ -465,7 +572,7 @@ function hasHighEntropyToken(text) {
     }
     return null;
 }
-/** Every string leaf in the note, `path` = dotted field name for the refusal. */
+/** Every string leaf in a claim note, `path` = dotted field name for the refusal. */
 function* noteStringLeaves(note) {
     yield { path: "summary", text: note.summary };
     for (const [group, arr] of [
@@ -491,9 +598,10 @@ function* noteStringLeaves(note) {
 /**
  * Refuse a note that carries a bare secret — no override flag exists
  * (design D10): a note is read by another agent, and secrets have the
- * secrets API. `null` when the note is clean.
+ * secrets API. `null` when the note is clean. Shared implementation for
+ * every claim-note kind.
  */
-export function scanHandoffNoteForSecrets(note) {
+function scanNoteForSecrets(note) {
     for (const { path, text } of noteStringLeaves(note)) {
         for (const re of HANDOFF_NOTE_SECRET_PREFIXES) {
             if (re.test(text))
@@ -505,6 +613,18 @@ export function scanHandoffNoteForSecrets(note) {
     }
     return null;
 }
+/**
+ * Refuse a note that carries a bare secret — no override flag exists
+ * (design D10): a note is read by another agent, and secrets have the
+ * secrets API. `null` when the note is clean.
+ */
+export function scanHandoffNoteForSecrets(note) {
+    return scanNoteForSecrets(note);
+}
+/** The invite-kind sibling of {@link scanHandoffNoteForSecrets} (kygit-invite design D3). */
+export function scanInviteNoteForSecrets(note) {
+    return scanNoteForSecrets(note);
+}
 /** Throws `HANDOFF_NOTE_CONTAINS_SECRET` naming the field — call before the handoff commit is written. */
 export function assertHandoffNoteHasNoSecret(note) {
     const finding = scanHandoffNoteForSecrets(note);
@@ -512,4 +632,11 @@ export function assertHandoffNoteHasNoSecret(note) {
         fail("HANDOFF_NOTE_CONTAINS_SECRET", `the handoff note's \`${finding.field}\` ${finding.reason} — edit the note; secrets belong in the secrets API, never in a note another agent will read`, "scanning handoff note", { field: finding.field });
     }
 }
+/** Throws `INVITE_NOTE_CONTAINS_SECRET` naming the field — call before the invite commit is written (kygit-invite design D3). */
+export function assertInviteNoteHasNoSecret(note) {
+    const finding = scanInviteNoteForSecrets(note);
+    if (finding) {
+        fail("INVITE_NOTE_CONTAINS_SECRET", `the invite note's \`${finding.field}\` ${finding.reason} — edit the note; secrets belong in the secrets API, never in a note another agent will read`, "scanning invite note", { field: finding.field });
+    }
+}
 //# sourceMappingURL=gitvault-handoff.js.map