@forgesworn/fold-kit 0.6.0 → 0.7.0

package/dist/seal.js

@@ -0,0 +1,128 @@
+import { schnorr } from '@noble/curves/secp256k1.js';
+import { nip44 } from 'nostr-tools';
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
+import { hexEquals, normaliseHex } from './hex.js';
+/**
+ * Seal keys: how a device heals after its key is copied.
+ *
+ * A device key signs, and until now every rekey copy and every epoch grant
+ * was also sealed to it. Whoever copied it opened every one after, until
+ * somebody noticed and removed the device. Rotating a receiving key signed
+ * by the device key would heal nothing: the thief holds that key and signs
+ * their own rotation.
+ *
+ * So the receiving key rides in the device credential (kind 20460), which
+ * the participant signs. A device mints a fresh seal key at every renewal,
+ * and its participant's signer, not the device, binds it. Rekeys and grants
+ * are sealed to the seal key of the newest credential the sender holds for
+ * the device. A thief who copied the device once holds the seal keys minted
+ * up to then, and none minted after: once the copied credential has lapsed
+ * and the room has rekeyed, they are out.
+ *
+ * A device keeps its seal secrets as it keeps its device key, to open what
+ * was sealed to them when it reads the room again. Healing needs only that
+ * each new one is fresh; retiring old ones is a question of forward
+ * secrecy, not of healing.
+ *
+ * A credential with no `seal` tag is sealed to as before, to the device
+ * key, so a client that knows nothing of this keeps working, unhealed. See
+ * docs/seal-key.md.
+ */
+/** The credential tag that names a device's seal key. */
+export const SEAL_TAG = 'seal';
+const HEX64 = /^[0-9a-f]{64}$/i;
+/** True for an x-only secp256k1 public key: 32-byte hex that lifts to a
+ *  point on the curve, so NIP-44 can agree a key with it. */
+export function isSealPubkey(value) {
+    if (typeof value !== 'string' || !HEX64.test(value))
+        return false;
+    try {
+        schnorr.utils.lift_x(BigInt(`0x${value}`));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A fresh seal key, for the next credential this device asks for. */
+export function generateSealKey() {
+    const secretKey = generateSecretKey();
+    return { secretKey, pubkey: getPublicKey(secretKey) };
+}
+/**
+ * The seal key a credential names. Undefined when it names none, and null
+ * when its `seal` tags are unusable: more than one, or one that is not a
+ * point on the curve. Only the participant could have signed either, so
+ * nothing here is an attack, but a sender must not throw on it mid-rekey:
+ * it treats null as none.
+ */
+export function credentialSeal(credential) {
+    const tags = credential.tags.filter((t) => t[0] === SEAL_TAG);
+    if (tags.length === 0)
+        return undefined;
+    if (tags.length > 1)
+        return null;
+    const value = tags[0][1];
+    return isSealPubkey(value) ? normaliseHex(value) : null;
+}
+/**
+ * Where to seal something for `device`: the seal key `credential` names, or
+ * the device key when it names none, or is not this device's.
+ *
+ * Expiry is deliberately not checked. A device that has gone quiet for
+ * longer than its credential kept that seal key, and opens the copy when it
+ * is back. Falling back to the device key instead would hand that copy to
+ * anybody holding a stolen device key, which is the one person healing
+ * exists to shut out.
+ */
+export function sealTarget(device, credential) {
+    const to = normaliseHex(device);
+    if (!credential)
+        return to;
+    const named = credential.tags.find((t) => t[0] === 'device')?.[1];
+    if (named === undefined || !hexEquals(named, to))
+        return to;
+    return credentialSeal(credential) ?? to;
+}
+/** Seal `plaintext` from `senderSk` to `device`, by `sealTarget`. */
+export function sealTo(plaintext, senderSk, device, credential) {
+    return nip44.v2.encrypt(plaintext, nip44.v2.utils.getConversationKey(senderSk, sealTarget(device, credential)));
+}
+/**
+ * Open something sealed to this device by `sender`: under each seal key in
+ * turn, then under the device key. Throws when none of them opens it.
+ * NIP-44's MAC verifies under the right key only, so a wrong one fails
+ * rather than producing garbage.
+ */
+export function openSealed(ciphertext, sender, deviceSk, sealSks = []) {
+    for (const sk of sealSks) {
+        try {
+            return nip44.v2.decrypt(ciphertext, nip44.v2.utils.getConversationKey(sk, sender));
+        }
+        catch {
+            // Not this one: try the next, then the device key.
+        }
+    }
+    return nip44.v2.decrypt(ciphertext, nip44.v2.utils.getConversationKey(deviceSk, sender));
+}
+function expirationOf(credential) {
+    const raw = credential.tags.find((t) => t[0] === 'expiration')?.[1];
+    const at = raw === undefined ? NaN : Number(raw);
+    return Number.isFinite(at) ? at : -Infinity;
+}
+/**
+ * The newer of two credentials: the later expiry, then the later
+ * `created_at`. Expiry first because some remote signers restamp
+ * `created_at` with their own clock (kithmoot#205), while the expiry is the
+ * device's own request, inside the signature either way. Ties keep `a`.
+ *
+ * Neither is checked here; compare only credentials already verified for
+ * the same device.
+ */
+export function newerCredential(a, b) {
+    const ea = expirationOf(a);
+    const eb = expirationOf(b);
+    if (eb !== ea)
+        return eb > ea ? b : a;
+    return b.created_at > a.created_at ? b : a;
+}

package/llms.txt

@@ -81,6 +81,7 @@ Not yet published to npm under this API. Until it is, pin an immutable Git commi
 - `hostRoomEpoch(opts)` / `requestRoomEpoch(opts)` / `EpochRefusedError` - the live request/grant desk, both sides
 - Member epoch catch-up (see `docs/member-epoch-catch-up.md`): `encodeRekeyEvent({ ..., commit: true })` writes `epochCommitment(roomId, epoch, secret)` into the rekey body; `hostMemberEpochDesk(opts)` lets any current member answer; `requestRoomEpoch({ ..., members: memberEpochSource(opts) })` asks the authority and members, first verifiable answer wins; `requestMemberEpoch(opts)` asks members alone. Kinds `MEMBER_EPOCH_KINDS` = `{ REQUEST: 20471, GRANT: 20472 }`. A member grant carries the authority-signed rekeys from the asker's epoch to the current one; the asker verifies the chain itself (`decodeMemberEpochGrant`) and refuses a last epoch with no commitment (legacy: authority only), a chain that removes it or closes the room, and one that stops short of `expected`. A verified grant is `{ epoch, removed, passed }`: `passed` holds the epochs between the asker's and `epoch`, oldest first, and `requestRoomEpoch` carries it as an optional `passed` when a member answered. Codecs: `encodeMemberEpochRequest`, `decodeMemberEpochRequest`, `encodeMemberEpochGrant`, `readRekeyEvidence`, `deriveMemberEpochRequestKey`, `MAX_MEMBER_EPOCH_CHAIN` (32)
 - The known-members gate (#207, see `docs/member-epoch-catch-up.md`): once a room has removed anybody (`removed()` not empty), `hostRoomEpoch` and `hostMemberEpochDesk` grant only to a participant for which `known(participant)` is true; anybody else is reported through `onUnknown` (once per participant, and again every `reportUnknownEvery` seconds, default `REPORT_UNKNOWN_EVERY_SECONDS` = 60, while they keep asking) and refused: the authority answers `refused: 'unknown'` (an `EpochRefusal`), a member stays silent. `unknown` is not final: `requestRoomEpoch` keeps asking, calls its `onUnknown` once, and rejects with `EpochRefusedError('unknown')` only at its timeout; a desk looks at the requester's next ask afresh, so letting somebody in is making `known` say yes. No `known` after a removal means nobody is known. Member lists: `encodeRekeyEvent({ members })` writes the authority's list (removed dropped, sorted) into the body, read back as `RekeyNotice.members` and `RekeyEvidence.members`, and as `MemberEpochGrant.members` (newest in the chain); `hostRoomEpoch({ members })` puts it in its grants (`EpochGrant.members`). `readMemberList(raw)` reads one, undefined when malformed. Without `members` and with no removal every event is byte-identical to 0.5.1
+- Seal keys (see `docs/seal-key.md`): `createDeviceCredential({ ..., seal })` appends `["seal", <x-only pubkey>]` last, under the participant's signature; mint a fresh one per credential with `generateSealKey()` and keep its secret as you keep the device key (old copies are sealed to old seal keys; healing needs only that each new one is fresh). `encodeRekeyEvent` recipients may be `{ device, credential }`; `encodeEpochGrant` and `encodeMemberEpochGrant` take `credential`; each copy is sealed to `sealTarget(device, credential)`: the credential's seal key, else the device key (never back to the device key because the credential lapsed). Readers take `sealSks` (`decodeRekeyEvent`, `decodeEpochGrant`, `decodeMemberEpochGrant`) or a `sealSks()` getter (`requestRoomEpoch`, `memberEpochSource`) and try them before the device key (`openSealed`); a rekey copy nothing opens reads as no copy. Desks take `credentialFor(device)`, the newest credential the room has seen (keep it monotone), and seal to the newer of that and the presented one (`sealCredential`, `newerCredential`: later expiration, then later created_at). `credentialSeal(c)` is the pubkey, undefined for none, null when doubled or off the curve (sealed to the device key). Without seal keys every event is byte-identical to 0.6.0
 - `canonicalAdmins(admins)` / `signAdmins(opts)` / `verifyAdmins(opts)` - the authority's signed admin list
 - `canonicalChannels(channels)` / `signChannels(opts)` / `verifyChannels(opts)` - the authority's signed channel list; `CHANNEL_NAME`, `RESERVED_CHANNELS`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/fold-kit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Circle primitives for private Nostr groups nobody operates: epoch keys, link invites, removal by rekey, device credentials.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,6 +21,7 @@
     "vectors/kithmoot-vectors.json",
     "vectors/circle-vectors.json",
     "vectors/member-epoch-vectors.json",
+    "vectors/seal-vectors.json",
     "LICENSE",
     "README.md",
     "llms.txt"
@@ -33,6 +34,7 @@
     "diff-source": "node scripts/diff-source.mjs",
     "generate-fold": "node scripts/generate-fold.mjs",
     "generate-member-epoch": "node scripts/generate-member-epoch.mjs",
+    "generate-seal": "node scripts/generate-seal.mjs",
     "bundle-check": "node scripts/bundle-check.mjs",
     "tarball-smoke": "node scripts/tarball-smoke.mjs",
     "vectors": "vitest run vectors/",