@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.149

package/dist/presence.js

@@ -0,0 +1,109 @@
+import { uuid as uuidCodec } from "./codec.js";
+import { mdbaseError } from "./errors.js";
+import { toValue } from "./values.js";
+import { presencePush } from "./wire.js";
+/** Presence state limit (§11). */
+export const MAX_PRESENCE_STATE = 4096;
+/** At most 10 updates per second per record; extra updates coalesce. */
+const MIN_INTERVAL_MS = 100;
+export class PresenceApi {
+    client;
+    joined = new Map();
+    watchers = new Map();
+    wired = new WeakSet();
+    constructor(client) {
+        this.client = client;
+        client.onSession(async (s) => {
+            this.wire(s);
+            // Rejoin and resubscribe after a reconnect.
+            for (const [id, j] of this.joined)
+                await s.request("presence_join", this.params(id, j.state));
+            for (const id of this.watchers.keys())
+                await s.request("subscribe_presence", new Map([[0, uuidCodec.enc(id)]]));
+        });
+    }
+    wire(s) {
+        if (this.wired.has(s))
+            return;
+        this.wired.add(s);
+        s.onPush("presence", (p) => {
+            try {
+                const v = presencePush.dec(p);
+                for (const fn of this.watchers.get(v.record) ?? [])
+                    fn(v.peers);
+            }
+            catch {
+                // ignore
+            }
+        });
+    }
+    params(record, state) {
+        return new Map([
+            [0, uuidCodec.enc(record)],
+            [1, state],
+        ]);
+    }
+    check(state) {
+        // A cheap size bound; the replica enforces the exact limit.
+        const n = JSON.stringify(state, (_k, v) => (typeof v === "bigint" ? v.toString() : v instanceof Map ? [...v] : v)).length;
+        if (n > MAX_PRESENCE_STATE) {
+            throw mdbaseError("too_large", "presence state over 4 KiB", { details: new Map([["limit", MAX_PRESENCE_STATE]]) });
+        }
+    }
+    async join(record, state) {
+        const v = toValue(state);
+        this.check(v);
+        this.joined.set(record, { state: v, last: Date.now(), timer: null });
+        const s = await this.client.ready();
+        this.wire(s);
+        await s.request("presence_join", this.params(record, v));
+    }
+    /** Update state; calls faster than 10/s coalesce into the latest state. */
+    update(record, state) {
+        const j = this.joined.get(record);
+        if (!j)
+            throw mdbaseError("invalid_request", "join the record's presence first");
+        j.state = toValue(state);
+        this.check(j.state);
+        if (j.timer)
+            return;
+        const wait = Math.max(0, j.last + MIN_INTERVAL_MS - Date.now());
+        j.timer = setTimeout(() => {
+            j.timer = null;
+            j.last = Date.now();
+            if (this.joined.get(record) !== j)
+                return;
+            void this.client.call("presence_update", this.params(record, j.state)).catch(() => { });
+        }, wait);
+    }
+    async leave(record) {
+        const j = this.joined.get(record);
+        if (j?.timer)
+            clearTimeout(j.timer);
+        this.joined.delete(record);
+        await this.client.call("presence_leave", new Map([[0, uuidCodec.enc(record)]])).catch(() => { });
+    }
+    /** Watch the peers on a record. Returns an unsubscribe function. */
+    subscribe(record, fn) {
+        let set = this.watchers.get(record);
+        const first = !set;
+        if (!set)
+            this.watchers.set(record, (set = new Set()));
+        set.add(fn);
+        if (first) {
+            void this.client
+                .ready()
+                .then((s) => {
+                this.wire(s);
+                return s.request("subscribe_presence", new Map([[0, uuidCodec.enc(record)]]));
+            })
+                .catch(() => { });
+        }
+        return () => {
+            set.delete(fn);
+            if (set.size === 0)
+                this.watchers.delete(record);
+        };
+    }
+}
+//# sourceMappingURL=presence.js.map

package/dist/presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"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"}

package/dist/private-account.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Private (E2E) multi-device enrolment with the account key (AK1,
+ * account-key bundle design): setup, unlock, change
+ * password, recover and strict mode, over two narrow host ports.
+ *
+ * - {@link AccountKeyControlPort}: the Connect client's authenticated account-key routes
+ *   (§5). The host owns the connector bearer, the device identity, challenges and the
+ *   device proof signature; the SDK never sees a bearer or signs as the device.
+ * - {@link AccountKeyReplicaPort}: the replica's account-key operations (§6) for each
+ *   private collection this device has open. The replica derives the recovery device
+ *   from `R`, checks the enrolment and appends grants; the SDK never
+ *   builds log items.
+ *
+ * `R` is held only in the {@link AccountSecretStore} (RAM by default; hosts supply the
+ * platform keychain, never a file) and wiped from working buffers after each step.
+ * Every step re-checks the caller's signal; a committed control-plane write is never
+ * reported cancelled.
+ */
+import { type Argon2idRunner, type Entropy } from "./account-key.js";
+import { type Strength } from "./strength.js";
+export interface PrivateAccountRequestOptions {
+    signal?: AbortSignal;
+}
+export type AccountKeyMode = "none" | "password" | "strict";
+export interface PrivateAccountStatus {
+    mode: AccountKeyMode;
+    /** This device holds `R` (set up, unlocked or recovered here, and not locked since). */
+    unlocked: boolean;
+    /** The control plane's compare-and-set version. */
+    version: number;
+    /** Strict-only, CP-authoritative completion across all private recovery targets. */
+    strictComplete?: boolean;
+    /** Strict-only CP missing witnesses; never inferred from locally open collections. */
+    pending?: StrictPendingTarget[];
+    /** Strict-only: this device still holds R. `status()` is read-only. */
+    accountKeyKept?: boolean;
+}
+export interface StrictPendingTarget {
+    collectionId: string;
+    deviceId: string;
+    /** Log revocation position, or null while it has not yet been appended. */
+    revokedAt: number | null;
+}
+/**
+ * The account-key control routes (AK1 §5.2–5.3), implemented by the Connect client for
+ * its signed-in account. Each method performs exactly one fixed route with the caller's
+ * device proof; responses are returned raw and validated by the SDK. Errors may be any
+ * object; the SDK reads `status`, `code`/`problem.code` and `retryAfterMs`/`retry_after`.
+ */
+export interface AccountKeyControlPort {
+    /** The signed-in account (the connector's user), which the bundle is bound to. */
+    readonly accountId: string;
+    /** Budget-free status; strict includes CP `complete` and `pending` witnesses. */
+    status(options: PrivateAccountRequestOptions): Promise<unknown>;
+    /** `GET /v1/next/account-key` → `{mode, version, key_id?, bundle?}`: the bundle; rate-limited (10 per hour per account). */
+    fetch(options: PrivateAccountRequestOptions): Promise<unknown>;
+    /** `PUT /v1/next/account-key` → `{mode: "password", version, key_id}`. `proof_pk`/`proof_sig` are the account key's proof (§5.2). */
+    put(body: {
+        expected_version: number;
+        key_id: string;
+        bundle: string;
+        proof_pk: string;
+        proof_sig: string;
+    }, options: PrivateAccountRequestOptions): Promise<unknown>;
+    /** Strict response includes `version`, CP `complete`/`pending`, and `revocations`; retries retain version. */
+    strict(body: {
+        expected_version: number;
+    }, options: PrivateAccountRequestOptions): Promise<unknown>;
+    /** A fresh single-use challenge (`POST /v1/next/devices/challenge`, 64 hex) the host will also prove with. */
+    challenge(options: PrivateAccountRequestOptions): Promise<unknown>;
+    /** `POST /v1/next/collections/:id/private/account-key-device` with the host's proof over the same challenge. */
+    enrolRecoveryDevice(collectionId: string, body: {
+        challenge: string;
+        recovery_device: string;
+        sign_pk: string;
+        kem_pk: string;
+        pop: string;
+    }, options: PrivateAccountRequestOptions): Promise<unknown>;
+    close?(): void;
+}
+/**
+ * The replica side (AK1 §6), per private collection this device has open. Both calls
+ * take `R`; the replica derives the collection's recovery device, refuses outside e2e
+ * or when the enrolment does not carry the derived keys, and never keeps `R`.
+ */
+export interface AccountKeyReplicaPort {
+    /** Private (e2e) collections of this account that this device has open. */
+    privateCollections(options: PrivateAccountRequestOptions): Promise<string[]>;
+    /** Setup step 2: check the enrolment and append the editor `key_grant` to the recovery device. */
+    keyAccountKeyDevice(collectionId: string, secret: Uint8Array, options: PrivateAccountRequestOptions): Promise<void>;
+    /** Unlock step 3: self-grant signed by the recovery device; resolves once this device is keyed. */
+    selfGrantWithAccountKey(collectionId: string, secret: Uint8Array, options: PrivateAccountRequestOptions): Promise<void>;
+}
+/** Where `R` lives between calls: the platform keychain, supplied by the host (never a file). */
+export interface AccountSecretStore {
+    get(): Promise<Uint8Array | null>;
+    set(secret: Uint8Array): Promise<void>;
+    clear(): Promise<void>;
+}
+/** RAM only, for tests and short-lived tools. Production hosts inject the platform keychain. */
+export declare function memorySecretStore(): AccountSecretStore;
+export interface PrivateAccountPorts {
+    control: AccountKeyControlPort;
+    replica: AccountKeyReplicaPort;
+    /** The platform keychain (never a file). `memorySecretStore()` is for tests only. */
+    secrets: AccountSecretStore;
+    /** Off-thread Argon2id; the default runs on the calling thread. */
+    argon2id?: Argon2idRunner;
+    entropy?: Entropy;
+}
+export interface SetupResult {
+    /** Shown once; the user saves it. The SDK does not keep the text. */
+    recoveryKey: string;
+    /** Private collections whose recovery device could not be enrolled or keyed now; retry with `keyCollections`. */
+    incomplete?: string[];
+}
+export interface StrictResult {
+    version: number;
+    /** Only the CP's explicit true permits local R deletion. */
+    complete: boolean;
+    pending: StrictPendingTarget[];
+    accountKeyKept: boolean;
+    /** Recovery devices the control plane queued for revocation; each collection rekeys when a keyed device applies it. */
+    revocations: {
+        collectionId: string;
+        deviceId: string;
+    }[];
+    alreadyStrict: boolean;
+}
+export interface UnlockResult {
+    /** Private collections where the self-grant was refused or failed; retry with `unlock` once they are current. */
+    incomplete?: string[];
+}
+/** Setup, unlock and recovery for private collections (AK1 §7). */
+export declare class PrivateAccount {
+    private readonly lifetime;
+    private readonly control;
+    private readonly replica;
+    private readonly secrets;
+    private readonly argon2id;
+    private readonly entropy;
+    /** One account-key operation at a time: they all compare-and-set the same version. */
+    private busy;
+    private last;
+    constructor(ports: PrivateAccountPorts);
+    /** Stops this facade. `R` stays in the secret store (the host owns its lifetime). */
+    close(): void;
+    /** Local and synchronous; the server never sees the password. */
+    passwordStrength(password: string): Strength;
+    /** The account's mode from the status route (no bundle, not on the fetch budget). */
+    status(options?: PrivateAccountRequestOptions): Promise<PrivateAccountStatus>;
+    /** The last `status()` answer, without a request; `null` before the first fetch. */
+    get lastStatus(): PrivateAccountStatus | null;
+    /** First private collection, device A (§3.1). The recovery key is returned once. */
+    setup(password: string, signal?: AbortSignal): Promise<SetupResult>;
+    /** New device B, same account (§3.2): opens the bundle and self-grants in every private collection. */
+    unlock(secret: {
+        password: string;
+    } | {
+        recoveryKey: string;
+    }, signal?: AbortSignal): Promise<UnlockResult>;
+    /** Re-wrap the same `R` (same key id); nothing on any log changes. Requires unlocked. */
+    changePassword(newPassword: string, signal?: AbortSignal): Promise<void>;
+    /** Forgotten password: the recovery key opens the account, and a new bundle wraps the same `R`. */
+    recover(recoveryKey: string, newPassword: string, signal?: AbortSignal): Promise<UnlockResult>;
+    /**
+     * Account-level strict mode (§3.3). The control plane deletes the bundle, records
+     * strict, and queues a `device-revoke` for each listed recovery device; the result is
+     * NOT complete protection: each collection is rekeyed only when one of its keyed
+     * devices applies that revocation, and content keyed before then stays readable to
+     * whoever held the old bundle and password. The UI shows the pending revocations and
+     * says so. R stays here until explicit CP completion; repeat this operation to
+     * forget it after witnesses arrive. Leaving strict is `setup` with a new key.
+     */
+    enableStrict(signal?: AbortSignal): Promise<StrictResult>;
+    /**
+     * Setup step 2 for every private collection this device has open (also for private
+     * collections created after setup, §3.1.3). Requires unlocked. Returns the
+     * collections that are still incomplete.
+     */
+    keyCollections(signal?: AbortSignal): Promise<string[]>;
+    /** Forget `R` on this device. Keys already granted to this device stay; a later `unlock` is needed to key new collections. */
+    lock(): Promise<void>;
+    private serial;
+    private check;
+    private readStatus;
+    private fetchState;
+    private requirePassword;
+    /** Store a bundle with the account key's proof: the proof key registered with it, and a signature over this rewrap. */
+    private putBundle;
+    private collections;
+    /** Enrol and key the recovery device in each private collection; collect the ones that failed. */
+    private keyAll;
+    private grantAll;
+    /** §5.3: the control plane enrols the derived recovery device, with a proof of possession by its signing key. */
+    private enrol;
+}