@941design/marmot 0.0.0-stage → 0.2.0-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +739 -0
- package/LICENSE +21 -0
- package/README.md +33 -2
- package/dist/account/admin.d.ts +72 -0
- package/dist/account/admin.js +209 -0
- package/dist/account/device-deps.d.ts +379 -0
- package/dist/account/device-deps.js +36 -0
- package/dist/account/device-lineage.d.ts +199 -0
- package/dist/account/device-lineage.js +390 -0
- package/dist/account/device-registry.d.ts +93 -0
- package/dist/account/device-registry.js +1290 -0
- package/dist/account/device-rotation.d.ts +61 -0
- package/dist/account/device-rotation.js +827 -0
- package/dist/account/enrolment.d.ts +339 -0
- package/dist/account/enrolment.js +1247 -0
- package/dist/account/identity-proof.d.ts +79 -0
- package/dist/account/identity-proof.js +264 -0
- package/dist/account/index.d.ts +17 -0
- package/dist/account/index.js +16 -0
- package/dist/account/restore-rotation.d.ts +21 -0
- package/dist/account/restore-rotation.js +22 -0
- package/dist/account/same-account-authorization.d.ts +86 -0
- package/dist/account/same-account-authorization.js +180 -0
- package/dist/account/teardown.d.ts +190 -0
- package/dist/account/teardown.js +878 -0
- package/dist/client/admission-cleanup.d.ts +197 -0
- package/dist/client/admission-cleanup.js +635 -0
- package/dist/client/adoption-proof.d.ts +39 -0
- package/dist/client/adoption-proof.js +102 -0
- package/dist/client/before-create-group.d.ts +18 -0
- package/dist/client/before-create-group.js +65 -0
- package/dist/client/before-publish-hooks.d.ts +121 -0
- package/dist/client/before-publish-hooks.js +182 -0
- package/dist/client/client-config.d.ts +42 -0
- package/dist/client/client-config.js +13 -0
- package/dist/client/commit-redrive.d.ts +92 -0
- package/dist/client/commit-redrive.js +274 -0
- package/dist/client/component-update.d.ts +43 -0
- package/dist/client/component-update.js +53 -0
- package/dist/client/confirm-hooks.d.ts +55 -0
- package/dist/client/confirm-hooks.js +74 -0
- package/dist/client/create-client.d.ts +1126 -0
- package/dist/client/create-client.js +1232 -0
- package/dist/client/group-availability.d.ts +182 -0
- package/dist/client/group-availability.js +301 -0
- package/dist/client/group-disband.d.ts +28 -0
- package/dist/client/group-disband.js +64 -0
- package/dist/client/group-history.d.ts +461 -0
- package/dist/client/group-history.js +1365 -0
- package/dist/client/group-profile.d.ts +31 -0
- package/dist/client/group-profile.js +62 -0
- package/dist/client/group-records.d.ts +522 -0
- package/dist/client/group-records.js +1117 -0
- package/dist/client/group-removal.d.ts +36 -0
- package/dist/client/group-removal.js +127 -0
- package/dist/client/group-remove-member.d.ts +49 -0
- package/dist/client/group-remove-member.js +163 -0
- package/dist/client/group-runtime.d.ts +415 -0
- package/dist/client/group-runtime.js +2811 -0
- package/dist/client/group-snapshot.d.ts +104 -0
- package/dist/client/group-snapshot.js +474 -0
- package/dist/client/history-pages.d.ts +107 -0
- package/dist/client/history-pages.js +194 -0
- package/dist/client/inbox-send.d.ts +19 -0
- package/dist/client/inbox-send.js +71 -0
- package/dist/client/index.d.ts +24 -0
- package/dist/client/index.js +13 -0
- package/dist/client/ingest.d.ts +82 -0
- package/dist/client/ingest.js +1584 -0
- package/dist/client/invitation-outcomes.d.ts +50 -0
- package/dist/client/invitation-outcomes.js +135 -0
- package/dist/client/lifecycle-events.d.ts +63 -0
- package/dist/client/lifecycle-events.js +35 -0
- package/dist/client/opaque-candidates.d.ts +82 -0
- package/dist/client/opaque-candidates.js +170 -0
- package/dist/client/own-change-outbox.d.ts +66 -0
- package/dist/client/own-change-outbox.js +158 -0
- package/dist/client/pending-leaf.d.ts +116 -0
- package/dist/client/pending-leaf.js +378 -0
- package/dist/client/permissions.d.ts +9 -0
- package/dist/client/permissions.js +12 -0
- package/dist/client/pipeline.d.ts +583 -0
- package/dist/client/pipeline.js +3666 -0
- package/dist/client/reentrancy-guard.d.ts +102 -0
- package/dist/client/reentrancy-guard.js +159 -0
- package/dist/client/rekey.d.ts +58 -0
- package/dist/client/rekey.js +149 -0
- package/dist/client/transport-policy.d.ts +181 -0
- package/dist/client/transport-policy.js +214 -0
- package/dist/history/admission-lineage.d.ts +186 -0
- package/dist/history/admission-lineage.js +589 -0
- package/dist/history/equivocation.d.ts +55 -0
- package/dist/history/equivocation.js +113 -0
- package/dist/history/fencing.d.ts +66 -0
- package/dist/history/fencing.js +121 -0
- package/dist/history/hex.d.ts +3 -0
- package/dist/history/hex.js +10 -0
- package/dist/history/index.d.ts +74 -0
- package/dist/history/index.js +32 -0
- package/dist/history/notifications.d.ts +270 -0
- package/dist/history/notifications.js +264 -0
- package/dist/history/ordering-key.d.ts +24 -0
- package/dist/history/ordering-key.js +101 -0
- package/dist/history/own-change-fork.d.ts +112 -0
- package/dist/history/own-change-fork.js +196 -0
- package/dist/history/own-change.d.ts +118 -0
- package/dist/history/own-change.js +146 -0
- package/dist/history/policy.d.ts +48 -0
- package/dist/history/policy.js +52 -0
- package/dist/history/retained-window.d.ts +215 -0
- package/dist/history/retained-window.js +565 -0
- package/dist/inbox/demux.d.ts +90 -0
- package/dist/inbox/demux.js +78 -0
- package/dist/inbox/handler-registry.d.ts +42 -0
- package/dist/inbox/handler-registry.js +37 -0
- package/dist/inbox/index.d.ts +11 -0
- package/dist/inbox/index.js +10 -0
- package/dist/inbox/seen-set.d.ts +82 -0
- package/dist/inbox/seen-set.js +202 -0
- package/dist/inbox/subscription.d.ts +236 -0
- package/dist/inbox/subscription.js +644 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +9 -0
- package/dist/invitations/competing-welcome.d.ts +223 -0
- package/dist/invitations/competing-welcome.js +128 -0
- package/dist/invitations/decline.d.ts +67 -0
- package/dist/invitations/decline.js +149 -0
- package/dist/invitations/delivery-evidence.d.ts +288 -0
- package/dist/invitations/delivery-evidence.js +766 -0
- package/dist/invitations/expect-welcome.d.ts +66 -0
- package/dist/invitations/expect-welcome.js +138 -0
- package/dist/invitations/index.d.ts +18 -0
- package/dist/invitations/index.js +18 -0
- package/dist/invitations/invitation-outcome.d.ts +110 -0
- package/dist/invitations/invitation-outcome.js +210 -0
- package/dist/invitations/invite.d.ts +358 -0
- package/dist/invitations/invite.js +1102 -0
- package/dist/invitations/offers.d.ts +79 -0
- package/dist/invitations/offers.js +115 -0
- package/dist/invitations/on-proposal.d.ts +47 -0
- package/dist/invitations/on-proposal.js +40 -0
- package/dist/invitations/pending-proposal-policy.d.ts +52 -0
- package/dist/invitations/pending-proposal-policy.js +139 -0
- package/dist/invitations/proposal-deadline.d.ts +133 -0
- package/dist/invitations/proposal-deadline.js +164 -0
- package/dist/invitations/relay-planes.d.ts +43 -0
- package/dist/invitations/relay-planes.js +70 -0
- package/dist/invitations/welcome-processor.d.ts +272 -0
- package/dist/invitations/welcome-processor.js +1241 -0
- package/dist/key-packages/device-key.d.ts +131 -0
- package/dist/key-packages/device-key.js +272 -0
- package/dist/key-packages/device-rotation-records.d.ts +83 -0
- package/dist/key-packages/device-rotation-records.js +173 -0
- package/dist/key-packages/group-refs.d.ts +40 -0
- package/dist/key-packages/group-refs.js +79 -0
- package/dist/key-packages/index.d.ts +18 -0
- package/dist/key-packages/index.js +18 -0
- package/dist/key-packages/key-package-ref.d.ts +16 -0
- package/dist/key-packages/key-package-ref.js +21 -0
- package/dist/key-packages/observation-stream.d.ts +4 -0
- package/dist/key-packages/observation-stream.js +120 -0
- package/dist/key-packages/offer-rumor.d.ts +26 -0
- package/dist/key-packages/offer-rumor.js +69 -0
- package/dist/key-packages/publisher.d.ts +174 -0
- package/dist/key-packages/publisher.js +1247 -0
- package/dist/key-packages/select-key-package.d.ts +24 -0
- package/dist/key-packages/select-key-package.js +90 -0
- package/dist/key-packages/slot-manager.d.ts +167 -0
- package/dist/key-packages/slot-manager.js +327 -0
- package/dist/key-packages/validate-key-package-event.d.ts +3 -0
- package/dist/key-packages/validate-key-package-event.js +49 -0
- package/dist/media/cache.d.ts +14 -0
- package/dist/media/cache.js +10 -0
- package/dist/media/index.d.ts +52 -0
- package/dist/media/index.js +71 -0
- package/dist/mls.d.ts +15 -0
- package/dist/mls.js +15 -0
- package/dist/shared/account-pubkey.d.ts +4 -0
- package/dist/shared/account-pubkey.js +10 -0
- package/dist/shared/errors.d.ts +28 -0
- package/dist/shared/errors.js +96 -0
- package/dist/shared/hex.d.ts +4 -0
- package/dist/shared/hex.js +13 -0
- package/dist/shared/index.d.ts +14 -0
- package/dist/shared/index.js +14 -0
- package/dist/shared/kinds.d.ts +8 -0
- package/dist/shared/kinds.js +28 -0
- package/dist/shared/publish-classification.d.ts +26 -0
- package/dist/shared/publish-classification.js +31 -0
- package/dist/storage/envelope.d.ts +39 -0
- package/dist/storage/envelope.js +201 -0
- package/dist/storage/index.d.ts +237 -0
- package/dist/storage/index.js +491 -0
- package/dist/storage/indexeddb/idb-types.d.ts +68 -0
- package/dist/storage/indexeddb/idb-types.js +1 -0
- package/dist/storage/indexeddb/index.d.ts +17 -0
- package/dist/storage/indexeddb/index.js +141 -0
- package/dist/storage/lease.d.ts +54 -0
- package/dist/storage/lease.js +168 -0
- package/dist/storage/memory/deterministic-signer.d.ts +27 -0
- package/dist/storage/memory/deterministic-signer.js +65 -0
- package/dist/storage/memory/index.d.ts +32 -0
- package/dist/storage/memory/index.js +87 -0
- package/dist/storage/memory/lock-manager.d.ts +8 -0
- package/dist/storage/memory/lock-manager.js +71 -0
- package/package.json +66 -3
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* KeyPackage → group refs (AccountStore `keyPackageGroupRefs`, AC-STORE-9;
|
|
3
|
+
* S9): the KeyPackages this account minted FOR a group — a
|
|
4
|
+
* `keyPackages.offer({ groupId })`, or one of an enrolment request's
|
|
5
|
+
* per-group KeyPackages — keyed by the KeyPackage event id, so
|
|
6
|
+
* `group.destroy()` can publish kind-5 for them (AC-ADMIN-7). Plus the purge
|
|
7
|
+
* of the key material a group's teardown leaves in the slot records: the
|
|
8
|
+
* `superseded` init keys a joined Welcome's KeyPackage keeps for the grace
|
|
9
|
+
* window.
|
|
10
|
+
*/
|
|
11
|
+
import type { AccountStoreTx } from '../storage/index.js';
|
|
12
|
+
export interface KeyPackageGroupRef {
|
|
13
|
+
/** The KeyPackage's kind-30443 event id (a `forget()` ref). */
|
|
14
|
+
readonly ref: string;
|
|
15
|
+
readonly groupId: string;
|
|
16
|
+
/** Client clock (ms). */
|
|
17
|
+
readonly at: number;
|
|
18
|
+
}
|
|
19
|
+
/** Records that the KeyPackage `ref` (its event id) was minted for `groupId`. */
|
|
20
|
+
export declare function recordKeyPackageGroupRef(tx: AccountStoreTx, entry: KeyPackageGroupRef): Promise<void>;
|
|
21
|
+
/** The refs recorded for `groupId`. A malformed entry is skipped (it names no group). */
|
|
22
|
+
export declare function keyPackageRefsOfGroup(tx: AccountStoreTx, groupId: string): Promise<string[]>;
|
|
23
|
+
/** Deletes every ref recorded for `groupId`. */
|
|
24
|
+
export declare function purgeKeyPackageGroupRefs(tx: AccountStoreTx, groupId: string): Promise<void>;
|
|
25
|
+
/**
|
|
26
|
+
* Whether the private key of KeyPackageRef `keyPackageRef` must not be kept
|
|
27
|
+
* as a `superseded` (grace-window) generation: its group was destroyed. S4's
|
|
28
|
+
* rotate settlement asks this in the transaction that would retain it.
|
|
29
|
+
*/
|
|
30
|
+
export declare function isKeyUnretained(tx: AccountStoreTx, keyPackageRef: string): Promise<boolean>;
|
|
31
|
+
/**
|
|
32
|
+
* Drops the retained (`superseded`, grace-window) private keys whose
|
|
33
|
+
* KeyPackageRef is in `keyPackageRefs` — the keys of KeyPackages a group's
|
|
34
|
+
* Welcome consumed — and marks each ref "never retain": a rotate-after-consume
|
|
35
|
+
* still in flight (the consumed key still the slot's current one) then drops
|
|
36
|
+
* the key when it settles instead of moving it into `superseded` (S9 C2).
|
|
37
|
+
* The caller passes only refs no other invitation relies on; a last-resort
|
|
38
|
+
* KeyPackage's refs are skipped here whatever the caller passes (S9 AA1).
|
|
39
|
+
*/
|
|
40
|
+
export declare function purgeRetainedKeyPackageKeys(tx: AccountStoreTx, keyPackageRefs: readonly string[], nowMs: number): Promise<void>;
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { listSlots, writeSlot } from './slot-manager.js';
|
|
2
|
+
const REFS = 'keyPackageGroupRefs';
|
|
3
|
+
function decodeRef(key, raw) {
|
|
4
|
+
if (typeof raw !== 'object' || raw === null)
|
|
5
|
+
return undefined;
|
|
6
|
+
const { groupId, at } = raw;
|
|
7
|
+
return typeof groupId === 'string' && typeof at === 'number' ? { ref: key, groupId, at } : undefined;
|
|
8
|
+
}
|
|
9
|
+
/** Records that the KeyPackage `ref` (its event id) was minted for `groupId`. */
|
|
10
|
+
export async function recordKeyPackageGroupRef(tx, entry) {
|
|
11
|
+
await tx.artifact(REFS).put(entry.ref, { groupId: entry.groupId, at: entry.at });
|
|
12
|
+
}
|
|
13
|
+
/** The refs recorded for `groupId`. A malformed entry is skipped (it names no group). */
|
|
14
|
+
export async function keyPackageRefsOfGroup(tx, groupId) {
|
|
15
|
+
const view = tx.artifact(REFS);
|
|
16
|
+
const out = [];
|
|
17
|
+
for (const key of await view.keys())
|
|
18
|
+
if (decodeRef(key, await view.get(key))?.groupId === groupId)
|
|
19
|
+
out.push(key);
|
|
20
|
+
return out;
|
|
21
|
+
}
|
|
22
|
+
/** Deletes every ref recorded for `groupId`. */
|
|
23
|
+
export async function purgeKeyPackageGroupRefs(tx, groupId) {
|
|
24
|
+
const view = tx.artifact(REFS);
|
|
25
|
+
for (const ref of await keyPackageRefsOfGroup(tx, groupId))
|
|
26
|
+
await view.delete(ref);
|
|
27
|
+
}
|
|
28
|
+
/** Prefix of the "never retain" markers {@link purgeRetainedKeyPackageKeys} leaves (same artifact, no groupId: never a ref). */
|
|
29
|
+
const UNRETAINED = 'unretained:';
|
|
30
|
+
/** A marker outlives any rotation it could meet (S4 retries a rotation for as long as its KeyPackage lives). */
|
|
31
|
+
const UNRETAINED_TTL_MS = 30 * 24 * 60 * 60 * 1000;
|
|
32
|
+
/**
|
|
33
|
+
* Whether the private key of KeyPackageRef `keyPackageRef` must not be kept
|
|
34
|
+
* as a `superseded` (grace-window) generation: its group was destroyed. S4's
|
|
35
|
+
* rotate settlement asks this in the transaction that would retain it.
|
|
36
|
+
*/
|
|
37
|
+
export async function isKeyUnretained(tx, keyPackageRef) {
|
|
38
|
+
return (await tx.artifact(REFS).get(`${UNRETAINED}${keyPackageRef}`)) !== undefined;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Drops the retained (`superseded`, grace-window) private keys whose
|
|
42
|
+
* KeyPackageRef is in `keyPackageRefs` — the keys of KeyPackages a group's
|
|
43
|
+
* Welcome consumed — and marks each ref "never retain": a rotate-after-consume
|
|
44
|
+
* still in flight (the consumed key still the slot's current one) then drops
|
|
45
|
+
* the key when it settles instead of moving it into `superseded` (S9 C2).
|
|
46
|
+
* The caller passes only refs no other invitation relies on; a last-resort
|
|
47
|
+
* KeyPackage's refs are skipped here whatever the caller passes (S9 AA1).
|
|
48
|
+
*/
|
|
49
|
+
export async function purgeRetainedKeyPackageKeys(tx, keyPackageRefs, nowMs) {
|
|
50
|
+
if (keyPackageRefs.length === 0)
|
|
51
|
+
return;
|
|
52
|
+
const view = tx.artifact('keyPackages');
|
|
53
|
+
const slots = await listSlots(view);
|
|
54
|
+
// AA1: a last-resort KeyPackage is shared by design (many inviters' Welcomes): its key is never marked or dropped.
|
|
55
|
+
const lastResort = new Set();
|
|
56
|
+
for (const slot of slots.filter((r) => r.lastResort)) {
|
|
57
|
+
for (const ref of [slot.currentRef, ...slot.published.map((e) => e.keyPackageRef), ...slot.superseded.map((e) => e.keyPackageRef)])
|
|
58
|
+
if (ref !== undefined)
|
|
59
|
+
lastResort.add(ref);
|
|
60
|
+
}
|
|
61
|
+
const refs = new Set(keyPackageRefs.filter((ref) => !lastResort.has(ref)));
|
|
62
|
+
if (refs.size === 0)
|
|
63
|
+
return;
|
|
64
|
+
const markers = tx.artifact(REFS);
|
|
65
|
+
for (const key of await markers.keys()) {
|
|
66
|
+
if (!key.startsWith(UNRETAINED))
|
|
67
|
+
continue;
|
|
68
|
+
const at = (await markers.get(key))?.at;
|
|
69
|
+
if (typeof at !== 'number' || at + UNRETAINED_TTL_MS < nowMs)
|
|
70
|
+
await markers.delete(key);
|
|
71
|
+
}
|
|
72
|
+
for (const ref of refs)
|
|
73
|
+
await markers.put(`${UNRETAINED}${ref}`, { at: nowMs });
|
|
74
|
+
for (const record of slots) {
|
|
75
|
+
const superseded = record.superseded.filter((s) => !refs.has(s.keyPackageRef));
|
|
76
|
+
if (superseded.length !== record.superseded.length)
|
|
77
|
+
await writeSlot(view, { ...record, superseded });
|
|
78
|
+
}
|
|
79
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `key-packages` module barrel (S4): slot manager, publisher,
|
|
3
|
+
* `selectKeyPackage`, observation stream, offer-rumor codec. Not
|
|
4
|
+
* re-exported from the package root (`src/index.ts`) — `MarmotClient
|
|
5
|
+
* .keyPackages.*` is the public surface (docs/client-api.md); this barrel
|
|
6
|
+
* is the in-repo seam other `marmot` modules import through, per
|
|
7
|
+
* architecture.md's dependencies_allowed table (`client` now, `invitations`
|
|
8
|
+
* / `account` from S5 / S8 on).
|
|
9
|
+
*/
|
|
10
|
+
export { createKeyPackage, rotateKeyPackage, purgeAllExpiredSuperseded, resumePendingIntents, probeParkedUnconfirmed, createParkedProbeState, type ParkedProbeState, forgetKeyPackage, retireKeyPackagesSignedWith, DEFAULT_CIPHERSUITE_NAME, type KeyPackageRetirementBlockReason, type KeyPackageRetirementOutcome, keyPackageStatus, listKeyPackages, countKeyPackages, fetchKeyPackageEvents, resolveWriteRelays, RESUME_BACKOFF_MS, type CreateKeyPackageOptions, type KeyPackageEventVerifier, type KeyPackagesDeps, type KeyPackagesRelayOptions, } from './publisher.js';
|
|
11
|
+
export { DEVICE_KEY_ENTRY, deviceProofSigner, ensureDeviceSigningKey, prepareDeviceKeyRotation, readDeviceSigningKey, withDeviceSignatureKey, type DeviceSigningKey, type PreparedDeviceKeyRotation, type PrepareDeviceKeyRotationInput, } from './device-key.js';
|
|
12
|
+
export { ROTATED_PREFIX, ROTATION_PREFIX, deviceKeyLinkKey, deviceKeyRotationKey, findOpenDeviceKeyRotation, isLeafKeyHex, moveRegistryEntry, readAllDeviceKeyLinks, readAllDeviceKeyRotations, readDeviceKeyLink, readDeviceKeyRotation, writeDeviceKeyLink, writeDeviceKeyRotation, type DeviceKeyLinkRecord, type DeviceKeyLinkSource, type DeviceKeyRotationGroup, type DeviceKeyRotationGroupOutcome, type DeviceKeyRotationRecord, type DeviceKeyRotationStatus, } from './device-rotation-records.js';
|
|
13
|
+
export { selectKeyPackage, type SelectedKeyPackage } from './select-key-package.js';
|
|
14
|
+
export { observeKeyPackages } from './observation-stream.js';
|
|
15
|
+
export { keyPackageRefsOfGroup, purgeKeyPackageGroupRefs, purgeRetainedKeyPackageKeys, recordKeyPackageGroupRef, type KeyPackageGroupRef } from './group-refs.js';
|
|
16
|
+
export { validateKeyPackageEvent } from './validate-key-package-event.js';
|
|
17
|
+
export { encodeKeyPackageOfferRumor, decodeKeyPackageOfferRumor, type DecodedKeyPackageOffer, type EncodeKeyPackageOfferRumorOptions } from './offer-rumor.js';
|
|
18
|
+
export { generateSlotId, computeKeyPackageRefHex, findPrivateKeyPackage, findKeyPackageEventByRef, type KeyPackageSlotRecord, type PendingIntent, type PublishedEntry, type SupersededEntry, } from './slot-manager.js';
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `key-packages` module barrel (S4): slot manager, publisher,
|
|
3
|
+
* `selectKeyPackage`, observation stream, offer-rumor codec. Not
|
|
4
|
+
* re-exported from the package root (`src/index.ts`) — `MarmotClient
|
|
5
|
+
* .keyPackages.*` is the public surface (docs/client-api.md); this barrel
|
|
6
|
+
* is the in-repo seam other `marmot` modules import through, per
|
|
7
|
+
* architecture.md's dependencies_allowed table (`client` now, `invitations`
|
|
8
|
+
* / `account` from S5 / S8 on).
|
|
9
|
+
*/
|
|
10
|
+
export { createKeyPackage, rotateKeyPackage, purgeAllExpiredSuperseded, resumePendingIntents, probeParkedUnconfirmed, createParkedProbeState, forgetKeyPackage, retireKeyPackagesSignedWith, DEFAULT_CIPHERSUITE_NAME, keyPackageStatus, listKeyPackages, countKeyPackages, fetchKeyPackageEvents, resolveWriteRelays, RESUME_BACKOFF_MS, } from './publisher.js';
|
|
11
|
+
export { DEVICE_KEY_ENTRY, deviceProofSigner, ensureDeviceSigningKey, prepareDeviceKeyRotation, readDeviceSigningKey, withDeviceSignatureKey, } from './device-key.js';
|
|
12
|
+
export { ROTATED_PREFIX, ROTATION_PREFIX, deviceKeyLinkKey, deviceKeyRotationKey, findOpenDeviceKeyRotation, isLeafKeyHex, moveRegistryEntry, readAllDeviceKeyLinks, readAllDeviceKeyRotations, readDeviceKeyLink, readDeviceKeyRotation, writeDeviceKeyLink, writeDeviceKeyRotation, } from './device-rotation-records.js';
|
|
13
|
+
export { selectKeyPackage } from './select-key-package.js';
|
|
14
|
+
export { observeKeyPackages } from './observation-stream.js';
|
|
15
|
+
export { keyPackageRefsOfGroup, purgeKeyPackageGroupRefs, purgeRetainedKeyPackageKeys, recordKeyPackageGroupRef } from './group-refs.js';
|
|
16
|
+
export { validateKeyPackageEvent } from './validate-key-package-event.js';
|
|
17
|
+
export { encodeKeyPackageOfferRumor, decodeKeyPackageOfferRumor } from './offer-rumor.js';
|
|
18
|
+
export { generateSlotId, computeKeyPackageRefHex, findPrivateKeyPackage, findKeyPackageEventByRef, } from './slot-manager.js';
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `keyPackageRefOf(event)` — the hex KeyPackageRef (RFC 9420 §5.2 `make_key_package_ref`, MIP-00) of a kind-30443
|
|
3
|
+
* KeyPackage event: what `invitations.expectWelcome()` takes as `keyPackageRef`, and what `keyPackages.rotate()` /
|
|
4
|
+
* `forget()` accept besides the event id. Public (package root) so a consumer holding the event that
|
|
5
|
+
* `keyPackages.create()` / `offer()` returned — or one fetched from a relay — needs no `@941design/marmot/mls`
|
|
6
|
+
* derivation of its own (marmot-public-keypackage-ref).
|
|
7
|
+
*
|
|
8
|
+
* It derives; it does not verify: the event's signature and the KeyPackage's own validity are not checked (an
|
|
9
|
+
* invitee's KeyPackage is validated where it is used — `group.invite()`).
|
|
10
|
+
*/
|
|
11
|
+
import type { NostrEvent } from '@941design/nostr-events/event';
|
|
12
|
+
/**
|
|
13
|
+
* The hex KeyPackageRef of `event`'s KeyPackage. Rejects `invalid-options` when `event` is not a kind-30443
|
|
14
|
+
* event whose content decodes as a framed MLS KeyPackage (`mls_key_package` wire format, base64).
|
|
15
|
+
*/
|
|
16
|
+
export declare function keyPackageRefOf(event: NostrEvent): Promise<string>;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { getKeyPackage } from '@941design/marmot-engine/core';
|
|
2
|
+
import { MarmotError } from '../shared/index.js';
|
|
3
|
+
import { computeKeyPackageRefHex } from './slot-manager.js';
|
|
4
|
+
const KEY_PACKAGE_KIND = 30443;
|
|
5
|
+
/**
|
|
6
|
+
* The hex KeyPackageRef of `event`'s KeyPackage. Rejects `invalid-options` when `event` is not a kind-30443
|
|
7
|
+
* event whose content decodes as a framed MLS KeyPackage (`mls_key_package` wire format, base64).
|
|
8
|
+
*/
|
|
9
|
+
export async function keyPackageRefOf(event) {
|
|
10
|
+
if (typeof event !== 'object' || event === null || event.kind !== KEY_PACKAGE_KIND || typeof event.content !== 'string') {
|
|
11
|
+
throw new MarmotError('invalid-options', 'keyPackageRefOf: not a kind-30443 KeyPackage event');
|
|
12
|
+
}
|
|
13
|
+
let keyPackage;
|
|
14
|
+
try {
|
|
15
|
+
keyPackage = getKeyPackage(event);
|
|
16
|
+
}
|
|
17
|
+
catch (cause) {
|
|
18
|
+
throw new MarmotError('invalid-options', 'keyPackageRefOf: the event content is not an MLS KeyPackage', { cause });
|
|
19
|
+
}
|
|
20
|
+
return computeKeyPackageRefHex(keyPackage);
|
|
21
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { NostrEvent } from '@941design/nostr-events/event';
|
|
2
|
+
import { type KeyPackagesDeps } from './publisher.js';
|
|
3
|
+
/** Opens the observation subscription; returns its `unsubscribe`. */
|
|
4
|
+
export declare function observeKeyPackages(deps: KeyPackagesDeps, account: string, listener: (event: NostrEvent) => void): () => void;
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `client.keyPackages.observe(account, listener)` (AC-KP-6): one live
|
|
3
|
+
* subscription for `account`'s kind-30443 events, each qualifying event
|
|
4
|
+
* reaching `listener` exactly once — even under relay redelivery (the
|
|
5
|
+
* transport contract makes no at-most-once promise) or a relay ignoring the
|
|
6
|
+
* filter it was asked.
|
|
7
|
+
*
|
|
8
|
+
* Gate-remediation F9: validity now goes through the SAME
|
|
9
|
+
* `validateKeyPackageEvent` predicate `select-key-package.ts` uses (single
|
|
10
|
+
* owner, no second copy of the kind/signature/credential checks), a
|
|
11
|
+
* qualifying event also passes the consumer's `verifier` when one is
|
|
12
|
+
* configured (ADR-008, same as the group ingest path), and the subscribe
|
|
13
|
+
* relays are resolved the same way `create()` resolves its publish relays
|
|
14
|
+
* (`resolveWriteRelays`) — for `relays.mode === 'discover'` that means
|
|
15
|
+
* `account`'s OWN newest kind-10002 write set, not necessarily the caller's.
|
|
16
|
+
* `'fixed'` mode stays synchronous (no discovery round-trip needed), so the
|
|
17
|
+
* subscription opens before `observe()` returns, as it always has.
|
|
18
|
+
*
|
|
19
|
+
* Gate-remediation R4: a `resolveWriteRelays` failure in `'discover'` mode
|
|
20
|
+
* falls back to `relays.defaults` rather than leaving `observe()` silently
|
|
21
|
+
* unsubscribed; the consumer's `listener` is called inside a try/catch so a
|
|
22
|
+
* throw from it never becomes an unhandled rejection; `deps.verifier` is
|
|
23
|
+
* already routed through `guard.call(ACCOUNT_SCOPE, 'verifier', ...)` by
|
|
24
|
+
* `client/create-client.ts` (matching `client/ingest.ts`'s own verifier
|
|
25
|
+
* call) — this module still wraps the call itself in a try/catch as
|
|
26
|
+
* defence-in-depth (e.g. against a `reentrant` rejection).
|
|
27
|
+
*
|
|
28
|
+
* Gate-remediation round 6 (F3): `open()` itself — `deps.subscription(...)`
|
|
29
|
+
* followed by `.subscribe(...)` — can throw (a misbehaving transport, or a
|
|
30
|
+
* consumer-supplied one in a test). Two call sites, two different
|
|
31
|
+
* obligations:
|
|
32
|
+
* - `'fixed'` mode calls `open()` SYNCHRONOUSLY, directly from
|
|
33
|
+
* `observeKeyPackages`'s own execution — it is not detached, so a throw
|
|
34
|
+
* here is left to propagate straight out to `observe()`'s own caller,
|
|
35
|
+
* exactly like any other synchronous `observe()` failure (e.g. a bad
|
|
36
|
+
* argument). This is a deliberate choice, not an oversight: swallowing
|
|
37
|
+
* it would silently hand back a no-op `unsubscribe` with no observation
|
|
38
|
+
* ever having started, which is worse than a loud synchronous failure
|
|
39
|
+
* the caller can catch and act on.
|
|
40
|
+
* - `'discover'` mode calls `open()` from inside a DETACHED `.then()` —
|
|
41
|
+
* `resolveWriteRelays(...)` is awaited with nothing left holding the
|
|
42
|
+
* promise chain once `observeKeyPackages` itself has already returned
|
|
43
|
+
* its `unsubscribe` function. A throw from `open()` here MUST be caught
|
|
44
|
+
* — otherwise it becomes an unhandled rejection with no caller able to
|
|
45
|
+
* do anything about it. Nothing extra needs tearing down on that catch:
|
|
46
|
+
* `open()` only ever assigns `subscriptionHandle` AFTER `.subscribe()`
|
|
47
|
+
* returns successfully, so a throw from either `deps.subscription(...)`
|
|
48
|
+
* or `.subscribe(...)` never leaves a partial/dangling handle behind —
|
|
49
|
+
* there is nothing to unsubscribe.
|
|
50
|
+
* - `open()`'s existing `if (disposed) return` guard (unchanged) already
|
|
51
|
+
* covers dispose-during-discovery: if `dispose()` runs while
|
|
52
|
+
* `resolveWriteRelays` is still in flight, `subscriptionHandle` stays
|
|
53
|
+
* `undefined` (nothing to tear down at dispose time), and when
|
|
54
|
+
* discovery finally resolves, `open()`'s own guard sees `disposed` and
|
|
55
|
+
* never creates a subscription at all.
|
|
56
|
+
*/
|
|
57
|
+
import { ADDRESSABLE_KEY_PACKAGE_KIND } from '@941design/marmot-engine/core';
|
|
58
|
+
import { resolveWriteRelays } from './publisher.js';
|
|
59
|
+
import { validateKeyPackageEvent } from './validate-key-package-event.js';
|
|
60
|
+
/** Opens the observation subscription; returns its `unsubscribe`. */
|
|
61
|
+
export function observeKeyPackages(deps, account, listener) {
|
|
62
|
+
const seen = new Set();
|
|
63
|
+
let disposed = false;
|
|
64
|
+
let subscriptionHandle;
|
|
65
|
+
async function handle(event) {
|
|
66
|
+
if (event.pubkey !== account)
|
|
67
|
+
return; // a relay is not obliged to honour the filter it was asked
|
|
68
|
+
if (seen.has(event.id))
|
|
69
|
+
return;
|
|
70
|
+
if (validateKeyPackageEvent(event) === undefined)
|
|
71
|
+
return; // F2/F9: kind, signature, credential<->pubkey — single owner
|
|
72
|
+
if (deps.verifier !== undefined) {
|
|
73
|
+
let ok;
|
|
74
|
+
try {
|
|
75
|
+
ok = await deps.verifier(event);
|
|
76
|
+
}
|
|
77
|
+
catch {
|
|
78
|
+
ok = false;
|
|
79
|
+
}
|
|
80
|
+
if (!ok)
|
|
81
|
+
return;
|
|
82
|
+
}
|
|
83
|
+
if (disposed || seen.has(event.id))
|
|
84
|
+
return; // re-check: the verifier awaited, a duplicate (or unsubscribe) may have landed meanwhile
|
|
85
|
+
seen.add(event.id);
|
|
86
|
+
try {
|
|
87
|
+
listener(event);
|
|
88
|
+
}
|
|
89
|
+
catch {
|
|
90
|
+
// A throwing consumer listener must not surface as an unhandled
|
|
91
|
+
// rejection out of this async chain (R4) — mirrors create-client.ts's
|
|
92
|
+
// own `emit()`, which swallows a throwing client-event listener.
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
function open(relays) {
|
|
96
|
+
if (disposed)
|
|
97
|
+
return;
|
|
98
|
+
const subscription = deps.subscription([...relays], { kinds: [ADDRESSABLE_KEY_PACKAGE_KIND], authors: [account] });
|
|
99
|
+
subscriptionHandle = subscription.subscribe({ next: (event) => void handle(event) });
|
|
100
|
+
}
|
|
101
|
+
if (deps.relays.mode === 'fixed') {
|
|
102
|
+
open(deps.relays.defaults); // synchronous, not detached — a throw here propagates to observe()'s own caller (documented above)
|
|
103
|
+
}
|
|
104
|
+
else {
|
|
105
|
+
void resolveWriteRelays(deps, account)
|
|
106
|
+
.catch(() => [...deps.relays.defaults]) // R4: a discovery failure falls back to defaults rather than leaving observe() silently unsubscribed
|
|
107
|
+
.then((relays) => {
|
|
108
|
+
try {
|
|
109
|
+
open(relays);
|
|
110
|
+
}
|
|
111
|
+
catch {
|
|
112
|
+
// F3: detached — never let a throw from open() become an unhandled rejection (documented above).
|
|
113
|
+
}
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
return () => {
|
|
117
|
+
disposed = true;
|
|
118
|
+
subscriptionHandle?.unsubscribe();
|
|
119
|
+
};
|
|
120
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { type NostrEvent, type Rumor } from '@941design/nostr-events/event';
|
|
2
|
+
export interface EncodeKeyPackageOfferRumorOptions {
|
|
3
|
+
/** The offering account's pubkey (the rumor's `pubkey`; the gift wrap's seal proves authorship separately). */
|
|
4
|
+
readonly pubkey: string;
|
|
5
|
+
/** The full signed kind-30443 event being offered. */
|
|
6
|
+
readonly keyPackageEvent: NostrEvent;
|
|
7
|
+
/** The group the offer targets — carried only inside this rumor, never as a tag on `keyPackageEvent`. */
|
|
8
|
+
readonly groupId: string;
|
|
9
|
+
/** Unix seconds. Required (not defaulted to the wall clock) so the codec stays pure and deterministic. */
|
|
10
|
+
readonly createdAt: number;
|
|
11
|
+
}
|
|
12
|
+
export interface DecodedKeyPackageOffer {
|
|
13
|
+
readonly keyPackageEvent: NostrEvent;
|
|
14
|
+
readonly groupId: string;
|
|
15
|
+
}
|
|
16
|
+
/** Builds the offer rumor (unsigned; no `sig`, per NIP-59). */
|
|
17
|
+
export declare function encodeKeyPackageOfferRumor(opts: EncodeKeyPackageOfferRumorOptions): Rumor;
|
|
18
|
+
/**
|
|
19
|
+
* Parses an offer rumor's payload. Never throws (D-08 typed-reject
|
|
20
|
+
* convention): malformed content, a wrong `kind`, a missing/malformed
|
|
21
|
+
* `keyPackageEvent`, a missing/empty `groupId`, or a `keyPackageEvent`
|
|
22
|
+
* authored by someone OTHER than the rumor's own `pubkey` (gate-remediation
|
|
23
|
+
* F11 — otherwise anyone could relay a stranger's KeyPackage inside a rumor
|
|
24
|
+
* claiming to be its offerer) all yield `undefined`.
|
|
25
|
+
*/
|
|
26
|
+
export declare function decodeKeyPackageOfferRumor(rumor: Rumor): DecodedKeyPackageOffer | undefined;
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The "KeyPackage offer" rumor codec (AC-KP-7; spec Design Decision 5):
|
|
3
|
+
* a targeted KeyPackage travels as a rumor carrying the full serialised
|
|
4
|
+
* (signed) kind-30443 event plus the target group id, gift-wrapped to one
|
|
5
|
+
* recipient — never as a group-identifying tag on the public kind-30443
|
|
6
|
+
* event itself. This module builds/parses the {@link Rumor} only; wrapping
|
|
7
|
+
* it in a NIP-59 gift wrap and sending it is the inviter/enrolment flow's
|
|
8
|
+
* job (S5 / S8).
|
|
9
|
+
*
|
|
10
|
+
* `RUMOR_KINDS.KEYPACKAGE_OFFER` is the S1-pinned constant (AC-API-8); this
|
|
11
|
+
* file never spells `4461` (enforced by kinds.test.ts's source-tree scan).
|
|
12
|
+
*/
|
|
13
|
+
import { ADDRESSABLE_KEY_PACKAGE_KIND } from '@941design/marmot-engine/core';
|
|
14
|
+
import { getEventHash } from '@941design/nostr-events/event';
|
|
15
|
+
import { RUMOR_KINDS } from '../shared/index.js';
|
|
16
|
+
/** Builds the offer rumor (unsigned; no `sig`, per NIP-59). */
|
|
17
|
+
export function encodeKeyPackageOfferRumor(opts) {
|
|
18
|
+
const payload = { v: 1, keyPackageEvent: opts.keyPackageEvent, groupId: opts.groupId };
|
|
19
|
+
const unsigned = {
|
|
20
|
+
pubkey: opts.pubkey,
|
|
21
|
+
kind: RUMOR_KINDS.KEYPACKAGE_OFFER,
|
|
22
|
+
created_at: opts.createdAt,
|
|
23
|
+
tags: [],
|
|
24
|
+
content: JSON.stringify(payload),
|
|
25
|
+
};
|
|
26
|
+
return { ...unsigned, id: getEventHash(unsigned) };
|
|
27
|
+
}
|
|
28
|
+
function isNostrEventShape(value) {
|
|
29
|
+
if (typeof value !== 'object' || value === null)
|
|
30
|
+
return false;
|
|
31
|
+
const e = value;
|
|
32
|
+
return (typeof e['id'] === 'string' &&
|
|
33
|
+
typeof e['pubkey'] === 'string' &&
|
|
34
|
+
e['kind'] === ADDRESSABLE_KEY_PACKAGE_KIND &&
|
|
35
|
+
typeof e['created_at'] === 'number' &&
|
|
36
|
+
typeof e['sig'] === 'string' &&
|
|
37
|
+
Array.isArray(e['tags']));
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Parses an offer rumor's payload. Never throws (D-08 typed-reject
|
|
41
|
+
* convention): malformed content, a wrong `kind`, a missing/malformed
|
|
42
|
+
* `keyPackageEvent`, a missing/empty `groupId`, or a `keyPackageEvent`
|
|
43
|
+
* authored by someone OTHER than the rumor's own `pubkey` (gate-remediation
|
|
44
|
+
* F11 — otherwise anyone could relay a stranger's KeyPackage inside a rumor
|
|
45
|
+
* claiming to be its offerer) all yield `undefined`.
|
|
46
|
+
*/
|
|
47
|
+
export function decodeKeyPackageOfferRumor(rumor) {
|
|
48
|
+
if (rumor.kind !== RUMOR_KINDS.KEYPACKAGE_OFFER)
|
|
49
|
+
return undefined;
|
|
50
|
+
let parsed;
|
|
51
|
+
try {
|
|
52
|
+
parsed = JSON.parse(rumor.content);
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
return undefined;
|
|
56
|
+
}
|
|
57
|
+
if (typeof parsed !== 'object' || parsed === null)
|
|
58
|
+
return undefined;
|
|
59
|
+
const payload = parsed;
|
|
60
|
+
if (payload['v'] !== 1)
|
|
61
|
+
return undefined;
|
|
62
|
+
if (!isNostrEventShape(payload['keyPackageEvent']))
|
|
63
|
+
return undefined;
|
|
64
|
+
if (typeof payload['groupId'] !== 'string' || payload['groupId'].length === 0)
|
|
65
|
+
return undefined;
|
|
66
|
+
if (payload['keyPackageEvent'].pubkey !== rumor.pubkey)
|
|
67
|
+
return undefined;
|
|
68
|
+
return { keyPackageEvent: payload['keyPackageEvent'], groupId: payload['groupId'] };
|
|
69
|
+
}
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
import { type CiphersuiteName } from '@941design/marmot-engine/mls';
|
|
2
|
+
import { type EventTemplate, type Filter, type NostrEvent } from '@941design/nostr-events/event';
|
|
3
|
+
import type { PublishResponse, RequestWithDeadlineResult, Subscribable } from '@941design/nostr-events/transport/contract';
|
|
4
|
+
import type { AccountStoreTx } from '../storage/index.js';
|
|
5
|
+
export declare const DEFAULT_CIPHERSUITE_NAME: CiphersuiteName;
|
|
6
|
+
export declare const RESUME_BACKOFF_MS = 30000;
|
|
7
|
+
export interface KeyPackagesRelayOptions {
|
|
8
|
+
readonly defaults: readonly string[];
|
|
9
|
+
readonly mode: 'discover' | 'fixed';
|
|
10
|
+
}
|
|
11
|
+
/** Matches `client/create-client.ts`'s `EventVerifier` structurally, without importing it (boundary rule). */
|
|
12
|
+
export type KeyPackageEventVerifier = (event: NostrEvent) => boolean | Promise<boolean>;
|
|
13
|
+
/**
|
|
14
|
+
* Everything `publisher.ts`/`observation-stream.ts` need from the client,
|
|
15
|
+
* already narrowed and — for `getPublicKey`/`signEvent`/`publish`/
|
|
16
|
+
* `requestWithDeadline`/`subscription`/`transaction`/`verifier` — already
|
|
17
|
+
* wrapped through the client's `ReentrancyGuard` and account-key signer by
|
|
18
|
+
* the caller (`client/create-client.ts`). This module never imports the
|
|
19
|
+
* guard or signer types itself.
|
|
20
|
+
*/
|
|
21
|
+
export interface KeyPackagesDeps {
|
|
22
|
+
readonly clock: {
|
|
23
|
+
now(): number;
|
|
24
|
+
};
|
|
25
|
+
/** Milliseconds (AC-KP-3). */
|
|
26
|
+
readonly graceWindowMs: number;
|
|
27
|
+
readonly relays: KeyPackagesRelayOptions;
|
|
28
|
+
/** Deadline for the 10002 write-relay discovery request (`relays.mode === 'discover'`). */
|
|
29
|
+
readonly historyTimeoutMs: number;
|
|
30
|
+
/**
|
|
31
|
+
* Consumer-supplied event check (ADR-008), run on every event `observe()`
|
|
32
|
+
* would otherwise emit (F9). Already routed through
|
|
33
|
+
* `guard.call(ACCOUNT_SCOPE, 'verifier', ...)` by the caller
|
|
34
|
+
* (gate-remediation R4) — this module never touches the guard itself.
|
|
35
|
+
*/
|
|
36
|
+
readonly verifier: KeyPackageEventVerifier | undefined;
|
|
37
|
+
getPublicKey(): Promise<string>;
|
|
38
|
+
signEvent(template: EventTemplate): Promise<NostrEvent>;
|
|
39
|
+
publish(relays: readonly string[], event: NostrEvent): Promise<Record<string, PublishResponse>>;
|
|
40
|
+
requestWithDeadline(relays: readonly string[], filters: Filter | Filter[], opts: {
|
|
41
|
+
timeoutMs: number;
|
|
42
|
+
}): Promise<RequestWithDeadlineResult>;
|
|
43
|
+
subscription(relays: readonly string[], filters: Filter | Filter[]): Subscribable<NostrEvent>;
|
|
44
|
+
/** This client's parked-event probe state ({@link probeParkedUnconfirmed}); one per client, created with {@link createParkedProbeState}. */
|
|
45
|
+
readonly parkedProbe: ParkedProbeState;
|
|
46
|
+
/** `AccountStore.transaction`, already routed through `guard.call(ACCOUNT_SCOPE, 'store', ...)` (F6) — every store access in this module goes through this, never a raw store reference. */
|
|
47
|
+
transaction<T>(fn: (tx: AccountStoreTx) => Promise<T> | T): Promise<T>;
|
|
48
|
+
}
|
|
49
|
+
/** Per-client, mutable state of {@link probeParkedUnconfirmed}. */
|
|
50
|
+
export interface ParkedProbeState {
|
|
51
|
+
/** A probe completed (or found nothing parked) since this client was built. */
|
|
52
|
+
done: boolean;
|
|
53
|
+
/** Client clock (ms) of the last probe attempt; retries wait {@link RESUME_BACKOFF_MS}. */
|
|
54
|
+
lastAttemptMs: number | undefined;
|
|
55
|
+
inFlight: boolean;
|
|
56
|
+
}
|
|
57
|
+
export declare function createParkedProbeState(): ParkedProbeState;
|
|
58
|
+
export interface CreateKeyPackageOptions {
|
|
59
|
+
readonly relays?: readonly string[];
|
|
60
|
+
readonly lastResort?: boolean;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Resolves the write-relay set for `pubkey`: an explicit `override` wins;
|
|
64
|
+
* else `relays.mode === 'fixed'` uses `relays.defaults` directly; else
|
|
65
|
+
* (`'discover'`) fetches `pubkey`'s newest VALID (signature- and, when
|
|
66
|
+
* configured, verifier-passing — C2) kind-10002 and takes its `write` set,
|
|
67
|
+
* falling back to `relays.defaults` on timeout/absence/no valid candidate/
|
|
68
|
+
* empty write set. Shared by `create()`, `rotate()` (F12: rotate re-resolves
|
|
69
|
+
* on every call) and `observeKeyPackages` (F9: "the same way create does"),
|
|
70
|
+
* parameterised on `pubkey` so `observe(account, ...)` resolves the
|
|
71
|
+
* OBSERVED account's relays, not necessarily the caller's own.
|
|
72
|
+
*/
|
|
73
|
+
export declare function resolveWriteRelays(deps: KeyPackagesDeps, pubkey: string, override?: readonly string[]): Promise<string[]>;
|
|
74
|
+
/**
|
|
75
|
+
* AC-KPL-1 after a crash or reload: an accepted event can stay parked in
|
|
76
|
+
* `unconfirmed` when the process stopped after a concurrent terminal resume
|
|
77
|
+
* parked it but before the accepting attempt committed. Until one probe
|
|
78
|
+
* completes on this client, asks the slots' relays for every `unconfirmed`
|
|
79
|
+
* event id in one batched request within `historyTimeoutMs`, and settles
|
|
80
|
+
* each event a relay returns (signature-checked, id-matched) through
|
|
81
|
+
* {@link settleParkedAcceptance}, oldest `created_at` first per slot. The
|
|
82
|
+
* probe counts as done only when the request completed without timing out
|
|
83
|
+
* (or nothing was parked); a failed or timed-out probe is retried at most
|
|
84
|
+
* once per {@link RESUME_BACKOFF_MS}, and meanwhile the entries simply stay
|
|
85
|
+
* in `unconfirmed` (reaped at `notAfter * 1000 + graceWindowMs`). Run by
|
|
86
|
+
* `create()`/`rotate()` and the inbox pass, never by `list()`/`count()`, so
|
|
87
|
+
* reads never wait on a relay.
|
|
88
|
+
*/
|
|
89
|
+
export declare function probeParkedUnconfirmed(deps: KeyPackagesDeps): Promise<void>;
|
|
90
|
+
/**
|
|
91
|
+
* Resolves every slot's pending intent, if any and if due (R2(4) backoff), by (re)publishing its already-signed event — idempotent, so a duplicate republish is harmless.
|
|
92
|
+
* Exported for S6: every inbox pass runs it, so an idle client still settles a rotation whose publish failed.
|
|
93
|
+
*/
|
|
94
|
+
export declare function resumePendingIntents(deps: KeyPackagesDeps): Promise<void>;
|
|
95
|
+
/**
|
|
96
|
+
* Round 6 stop-rule fix: also reaps `unconfirmed` entries past their OWN
|
|
97
|
+
* KeyPackage lifetime (`reapExpiredUnconfirmed`), alongside the existing
|
|
98
|
+
* `superseded` grace-window purge — one pass, one write per changed record.
|
|
99
|
+
* Exported for S6: every inbox pass runs this same purge.
|
|
100
|
+
*/
|
|
101
|
+
export declare function purgeAllExpiredSuperseded(deps: KeyPackagesDeps): Promise<void>;
|
|
102
|
+
/**
|
|
103
|
+
* S9 (`group.destroy()`): where `ref`'s KeyPackage stands locally — `absent`
|
|
104
|
+
* (no slot holds it: never minted here, already deleted, or superseded by a
|
|
105
|
+
* rotation), `deleting` (a `forget()`'s kind-5 is durably pending on its
|
|
106
|
+
* slot), or `present`.
|
|
107
|
+
*/
|
|
108
|
+
export declare function keyPackageStatus(deps: Pick<KeyPackagesDeps, 'transaction'>, ref: string): Promise<'absent' | 'deleting' | 'present'>;
|
|
109
|
+
export declare function createKeyPackage(deps: KeyPackagesDeps, options?: CreateKeyPackageOptions): Promise<NostrEvent>;
|
|
110
|
+
export declare function rotateKeyPackage(deps: KeyPackagesDeps, ref: string): Promise<NostrEvent>;
|
|
111
|
+
export declare function forgetKeyPackage(deps: KeyPackagesDeps, ref: string): Promise<void>;
|
|
112
|
+
/**
|
|
113
|
+
* S8 (`devices.forget`): every valid kind-30443 event `pubkey` has on its
|
|
114
|
+
* write relays (resolved like `create` resolves them) — each one passed
|
|
115
|
+
* {@link validateKeyPackageEvent} and the consumer verifier. `timedOut`:
|
|
116
|
+
* the answer may be incomplete. `relays` is where it was asked (a deletion
|
|
117
|
+
* goes there too).
|
|
118
|
+
*/
|
|
119
|
+
export declare function fetchKeyPackageEvents(deps: KeyPackagesDeps, pubkey: string): Promise<{
|
|
120
|
+
readonly events: readonly NostrEvent[];
|
|
121
|
+
readonly relays: readonly string[];
|
|
122
|
+
readonly timedOut: boolean;
|
|
123
|
+
}>;
|
|
124
|
+
export declare function listKeyPackages(deps: KeyPackagesDeps): Promise<readonly NostrEvent[]>;
|
|
125
|
+
export declare function countKeyPackages(deps: KeyPackagesDeps): Promise<number>;
|
|
126
|
+
/** Why one slot of a retirement is not finished; the next run (or a resume) retries it. */
|
|
127
|
+
export type KeyPackageRetirementBlockReason = 'pending-intent' | 'publish-failed' | 'no-relays' | 'no-current' | 'delete-pending' | 'relay-unreachable';
|
|
128
|
+
export interface KeyPackageRetirementOutcome {
|
|
129
|
+
/** Slots whose KeyPackage was replaced by one carrying the device key in this call. */
|
|
130
|
+
readonly replaced: readonly string[];
|
|
131
|
+
/** Slots whose retired-key events got an accepted kind-5 in this call. */
|
|
132
|
+
readonly deleted: readonly string[];
|
|
133
|
+
/** Slots with retired-key material this call could not finish. Empty when the retirement is complete. */
|
|
134
|
+
readonly blocked: readonly {
|
|
135
|
+
readonly dSlot: string;
|
|
136
|
+
readonly reason: KeyPackageRetirementBlockReason;
|
|
137
|
+
}[];
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Replaces every KeyPackage whose leaf signature key is in `keys` (Design
|
|
141
|
+
* Decision 10, AC-KP-1..5) — the last-resort slot included — by one carrying
|
|
142
|
+
* the device key and its stored proof, and then kind-5 deletes the retired-key
|
|
143
|
+
* events.
|
|
144
|
+
*
|
|
145
|
+
* Per slot, in order: (1) a slot whose current KeyPackage, or any possibly-live
|
|
146
|
+
* `unconfirmed` one that can still be live at the address (not replaced by the
|
|
147
|
+
* current event, not deleted) carries a retired key is `rotate()`d — the replacement is
|
|
148
|
+
* minted with the device key (`ensureDeviceSigningKey` = `self`) and published
|
|
149
|
+
* under the same `d` address, so the relay's addressable replacement swaps it in
|
|
150
|
+
* and there is never a moment with no advertised KeyPackage; (2) only once the
|
|
151
|
+
* replacement is accepted, a kind-5 over the retired events' IDS (`e` tags
|
|
152
|
+
* only — an address-scoped deletion would take the replacement with it) is
|
|
153
|
+
* signed once and sent only to relays known to hold the replacement (the current
|
|
154
|
+
* event is re-published first; the accepting relays count) plus the slot relays
|
|
155
|
+
* that left the write set, and recorded per relay in the slot's `deletions`; a
|
|
156
|
+
* relay still missing is retried by the next run. A deleted `unconfirmed`
|
|
157
|
+
* candidate moves to `superseded`. The superseded
|
|
158
|
+
* private material stays resolvable for the usual grace window
|
|
159
|
+
* (`findPrivateKeyPackage`), so a Welcome built against the old KeyPackage still
|
|
160
|
+
* joins. Signer cost per slot: the replacement event and the deletion — at most
|
|
161
|
+
* two, whatever the number of held groups.
|
|
162
|
+
*
|
|
163
|
+
* Idempotent and resumable: every step rests on the slot's durable record, so a
|
|
164
|
+
* run that stopped at any await boundary, run again, ends where an uninterrupted
|
|
165
|
+
* one would — a slot already on the device key is skipped, a deletion already
|
|
166
|
+
* recorded is not repeated. A slot it cannot finish (a stuck pending intent, no
|
|
167
|
+
* relay accepting) is reported in `blocked`, never thrown; any other error
|
|
168
|
+
* propagates.
|
|
169
|
+
*
|
|
170
|
+
* `keys` are 64-hex leaf keys. Rejects `invalid-options` when there is no device
|
|
171
|
+
* key yet (`reason: 'no-device-key'`) or when `keys` names the device key itself
|
|
172
|
+
* (`reason: 'retire-current-key'`).
|
|
173
|
+
*/
|
|
174
|
+
export declare function retireKeyPackagesSignedWith(deps: KeyPackagesDeps, keys: readonly string[]): Promise<KeyPackageRetirementOutcome>;
|