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

package/dist/app-grant/client.js

@@ -0,0 +1,930 @@
+/**
+ * Application grants for web apps: OAuth authorization code + PKCE against the
+ * Connect portal, with the grant's Noise client key registered at consent
+ * (`client_noise_key`, attested by the grant signing key), then thin-client sessions
+ * to a Private collection over the relay (Noise IK to one of the account's devices).
+ *
+ * The CP grant is only an offer: the collection's replica admits the app after the
+ * user approves it in the mdbase desktop app. Until then the collection is listed as
+ * `unavailable/approval_required`.
+ *
+ * Storage: see `grant-store.ts`. Access tokens stay in memory; the refresh token is
+ * encrypted under a non-extractable key; the Noise key is non-extractable.
+ */
+import { APPLICATION_AUTHORIZATION_PROTOCOL_VERSION, AUTHORITY_PROOF_DOMAIN, AUTHORITY_PROOF_HEADERS, AUTHORITY_PROOF_VERSION, applicationInstallationIdFromPublicKey, authorizationSigningMessage, } from "@mdbase-dev/connect-protocol";
+import { selectAppEnvironment } from "../app-host/app-environment.js";
+import { applicationDeclaration } from "../application/declaration.js";
+import { applicationStorageNamespace, applicationStorageOwner } from "../application/storage-scope.js";
+import { compileApplicationManifest } from "../application/manifest.js";
+import { appReleaseTrust } from "../application/packaged-trust.js";
+import { resolveApplicationRegistration } from "../application/registration.js";
+import { uuidToBytes } from "../codec.js";
+import { collectionUnavailableError, parseCollectionAvailability, } from "../collection-availability.js";
+import { isMdbaseError, mdbaseError } from "../errors.js";
+import { orderTargets } from "../transport/next-relay.js";
+import { clientPrologue } from "../transport/noise.js";
+import { noiseConnector } from "../transport/noise-session.js";
+import { registerNextRelayFence } from "../transport/read-fence-policy.js";
+import { relayPipeCarrier } from "../transport/relay-pipe.js";
+import { MdbasePeopleClient } from "../people.js";
+import { appGrantPeopleAuthority } from "./people.js";
+import { privateCollectionSetup } from "./setup.js";
+import { protectedSetupJournal } from "./setup-attempt.js";
+import { bindOriginalAppGrant, originalAppGrant } from "../transport/original-session.js";
+import { indexedDbAppGrantStore } from "./grant-store.js";
+import { nativeCompletionFromToken } from "./native-completion.js";
+const ROLES = new Set(["owner", "editor", "viewer"]);
+const CHANNEL = "mdbase.app-grant.v1";
+const UUID = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i;
+const REQUEST_MS = 15_000;
+function canonicalChallengeNonce(value) {
+    try {
+        const bytes = Uint8Array.from(atob(value.replaceAll("-", "+").replaceAll("_", "/")), c => c.charCodeAt(0));
+        return bytes.length === 32 && b64u(bytes) === value;
+    }
+    catch {
+        return false;
+    }
+}
+const P256_ORDER = BigInt("0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551");
+const NOISE_KEY_DOMAIN = new TextEncoder().encode("mdbase-next client noise key v1\0");
+/** Call from the redirect page with `location.href`; the waiting flow picks it up. */
+export function deliverAppGrantCallback(url) {
+    const Channel = globalThis.BroadcastChannel;
+    if (!Channel)
+        throw mdbaseError("unavailable", "BroadcastChannel is not available", "authorization_callback");
+    const channel = new Channel(CHANNEL);
+    channel.postMessage({ type: "callback", url: String(url) });
+    channel.close();
+}
+function broadcastCallbacks() {
+    return {
+        subscribe(listener) {
+            const Channel = globalThis.BroadcastChannel;
+            if (!Channel)
+                throw mdbaseError("unavailable", "BroadcastChannel is not available", "authorization_callback");
+            const channel = new Channel(CHANNEL);
+            channel.onmessage = (event) => {
+                const data = event.data;
+                if (data?.type === "callback" && typeof data.url === "string")
+                    listener(data.url);
+            };
+            return () => channel.close();
+        },
+    };
+}
+/** Cloud copies from the installation sign-in plus Private collections, by name. */
+export function mergeCollectionEntries(cloud, privates) {
+    const out = new Map();
+    for (const c of cloud) {
+        out.set(c.collectionId, Object.freeze({ collectionId: c.collectionId, displayName: c.displayName, kind: "cloud_copy", availability: c.availability ?? Object.freeze({ state: "available" }), role: c.role }));
+    }
+    for (const p of privates) {
+        if (!out.has(p.collectionId))
+            out.set(p.collectionId, Object.freeze({ collectionId: p.collectionId, displayName: p.displayName, kind: "private", availability: p.availability, role: p.role }));
+    }
+    return [...out.values()].sort((a, b) => a.displayName.localeCompare(b.displayName) || a.collectionId.localeCompare(b.collectionId));
+}
+const b64u = (bytes) => {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+};
+const random = (n) => crypto.getRandomValues(new Uint8Array(n));
+const u32 = (n) => { const b = new Uint8Array(4); new DataView(b.buffer).setUint32(0, n); return b; };
+const concat = (...parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+};
+/** Low-S P1363 ECDSA P-256 signature (what Connect and the daemon accept). */
+async function signP256(key, message) {
+    const sig = new Uint8Array(await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key, message));
+    if (sig.length !== 64)
+        throw mdbaseError("internal", "unexpected signature length", "authorization_signature");
+    let s = 0n;
+    for (const b of sig.subarray(32))
+        s = (s << 8n) | BigInt(b);
+    if (s <= P256_ORDER / 2n)
+        return sig;
+    let low = P256_ORDER - s;
+    for (let i = 63; i >= 32; i--) {
+        sig[i] = Number(low & 0xffn);
+        low >>= 8n;
+    }
+    return sig;
+}
+const sha256b64u = async (text) => b64u(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))));
+/** Connect's authority request proof headers: the grant's signing key over the
+ * request (method, target, body and credential digests, time and nonce). */
+async function authorityProof(key, target, body, credential) {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const nonce = crypto.randomUUID();
+    const message = [AUTHORITY_PROOF_DOMAIN, AUTHORITY_PROOF_VERSION, "POST", target,
+        await sha256b64u(body), await sha256b64u(credential), timestamp, nonce].join("\n");
+    return {
+        [AUTHORITY_PROOF_HEADERS.version]: String(AUTHORITY_PROOF_VERSION),
+        [AUTHORITY_PROOF_HEADERS.timestamp]: String(timestamp),
+        [AUTHORITY_PROOF_HEADERS.nonce]: nonce,
+        [AUTHORITY_PROOF_HEADERS.signature]: b64u(await signP256(key, new TextEncoder().encode(message))),
+    };
+}
+async function p256Pair(usages, algorithm) {
+    const pair = (await crypto.subtle.generateKey({ name: algorithm, namedCurve: "P-256" }, false, usages));
+    return { privateKey: pair.privateKey, publicKey: b64u(new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey))) };
+}
+async function noisePair() {
+    let pair;
+    try {
+        pair = (await crypto.subtle.generateKey({ name: "X25519" }, false, ["deriveBits"]));
+    }
+    catch {
+        throw mdbaseError("unavailable", "this browser cannot keep a non-extractable X25519 key", "browser_unsupported");
+    }
+    if (pair.privateKey.extractable)
+        throw mdbaseError("unavailable", "the Noise key must be non-extractable", "browser_unsupported");
+    return { privateKey: pair.privateKey, publicKey: new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey)) };
+}
+function staticKeyOf(grant) {
+    return {
+        publicKey: grant.noisePublicKey.slice(),
+        dh: async (remote) => {
+            const pub = await crypto.subtle.importKey("raw", remote, { name: "X25519" }, false, []);
+            return new Uint8Array(await crypto.subtle.deriveBits({ name: "X25519", public: pub }, grant.noisePrivateKey, 256));
+        },
+    };
+}
+function bounded(signal, ms) {
+    const control = new AbortController();
+    const abort = () => control.abort();
+    const timer = setTimeout(abort, ms);
+    timer.unref?.();
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted)
+        control.abort();
+    return { signal: control.signal, done: () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); } };
+}
+const equalBytes = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+const sameGrant = (a, b) => !!b && a.collection === b.collection && a.owner === b.owner && equalBytes(a.noisePublicKey, b.noisePublicKey);
+const sameRevision = (a, b) => sameGrant(a, b) && equalBytes(a.refresh, b.refresh);
+const grantChanged = () => mdbaseError("cancelled", "the stored grant changed during this operation");
+// Shared across instances in this host. Without Web Locks this is NOT a
+// cross-process/tab fence; browser writers all use the same exclusive Web Lock.
+const localLocks = new Map();
+async function exclusive(name, work) {
+    const locks = globalThis.navigator?.locks;
+    if (locks)
+        return locks.request(name, { mode: "exclusive" }, work);
+    const previous = localLocks.get(name) ?? Promise.resolve();
+    let release;
+    const pending = new Promise((resolve) => { release = resolve; });
+    localLocks.set(name, pending);
+    await previous;
+    try {
+        return await work();
+    }
+    finally {
+        release();
+        if (localLocks.get(name) === pending)
+            localLocks.delete(name);
+    }
+}
+/**
+ * Application grants of one app installation (a browser profile) against its
+ * Connect environment. Generic: no app-specific behaviour.
+ */
+export class MdbaseAppGrants {
+    options;
+    declaration;
+    cpOrigin;
+    redirect;
+    fetcher;
+    callbacks;
+    storeValue;
+    registration = null;
+    tokens = new Map();
+    refreshing = new Map();
+    forgotten = new Set();
+    /** Bumped by every whole-store wipe: work prepared under an older epoch
+     * (an authorization or token commit racing sign-out) must not re-save. */
+    epoch = 0;
+    constructor(options) {
+        this.options = options;
+        this.declaration = applicationDeclaration(options.declaration);
+        this.cpOrigin = selectAppEnvironment({ environment: this.declaration.environment, appOrigin: this.declaration.origin, release: appReleaseTrust() }).cpOrigin;
+        try {
+            this.redirect = new URL(options.redirectUri);
+        }
+        catch {
+            throw mdbaseError("invalid_request", "redirectUri must be an absolute URL", "redirect_uri");
+        }
+        if (this.redirect.origin !== this.declaration.origin || this.redirect.hash) {
+            throw mdbaseError("invalid_request", "redirectUri must be on the app's origin, without a fragment", "redirect_uri");
+        }
+        this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.callbacks = options.callbacks ?? broadcastCallbacks();
+        this.storeValue = options.store ?? null;
+    }
+    register() {
+        const pending = this.registration ??= resolveApplicationRegistration({
+            declaration: this.options.declaration, signal: new AbortController().signal, isCurrent: () => true, fetch: this.fetcher,
+        });
+        pending.catch(() => { if (this.registration === pending)
+            this.registration = null; });
+        return pending;
+    }
+    ownerValue = null;
+    /**
+     * The local owner of this app's grants: its manifest family from the ORIGINAL
+     * declaration plus an optional storage namespace, never the CP-assigned id.
+     * It labels the default store and binds
+     * the refresh ciphertext, so a wrong registration id cannot select, use or
+     * delete another app's grants.
+     */
+    owner() {
+        return this.ownerValue ??= applicationStorageOwner(compileApplicationManifest(this.declaration).manifest.id, applicationStorageNamespace(this.declaration));
+    }
+    async store() {
+        if (this.storeValue)
+            return this.storeValue;
+        const owner = this.owner();
+        return (this.storeValue = indexedDbAppGrantStore(this.cpOrigin, (await this.register()).id, { owner }));
+    }
+    async identity() {
+        const store = await this.store();
+        const existing = await store.getIdentity();
+        if (existing)
+            return existing;
+        const created = await p256Pair(["sign"], "ECDSA");
+        return store.putIdentityIfAbsent({ version: 1, privateKey: created.privateKey, publicKey: created.publicKey });
+    }
+    async request(path, init, signal) {
+        const budget = bounded(signal, REQUEST_MS);
+        try {
+            let res;
+            try {
+                res = await this.fetcher(`${this.cpOrigin}${path}`, { ...init, redirect: "error", signal: budget.signal });
+            }
+            catch {
+                if (signal?.aborted)
+                    throw mdbaseError("cancelled", "request cancelled");
+                throw mdbaseError("unavailable", "cannot reach the control plane", "control_unreachable");
+            }
+            let body = null;
+            try {
+                const parsed = await res.json();
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                    body = parsed;
+            }
+            catch {
+                body = null;
+            }
+            return { status: res.status, body };
+        }
+        finally {
+            budget.done();
+        }
+    }
+    /**
+     * Ask the person for access in the popup: Connect's consent lists their
+     * collections, including Private ones. Resolves with the approved collection.
+     * The collection then usually reports `approval_required` until the person also
+     * approves the app in the mdbase desktop app.
+     */
+    async authorize(o) {
+        o = Object.freeze({ ...o });
+        const prepared = await this.prepareAuthorization(o).catch(error => { o.popup.close(); throw error; });
+        try {
+            o.popup.navigate(prepared.authorizationUri);
+            const { collectionId } = await prepared.finish(o);
+            return { collectionId };
+        }
+        finally {
+            prepared.cancel();
+            try {
+                o.popup.close();
+            }
+            catch { /* original popup only */ }
+        }
+    }
+    async prepareAuthorization(o = {}) {
+        o = Object.freeze({ ...o });
+        if (o.collection !== undefined && !UUID.test(o.collection))
+            throw mdbaseError("invalid_request", "collection must be a UUID");
+        if (o.expectedAccountId !== undefined && (!UUID.test(o.expectedAccountId) || !o.authorizationNonce))
+            throw mdbaseError("invalid_request", "original account and challenge required", "authorization_binding");
+        if (o.authorizationNonce !== undefined && (!/^[A-Za-z0-9_-]{43}$/.test(o.authorizationNonce) || !canonicalChallengeNonce(o.authorizationNonce)))
+            throw mdbaseError("invalid_request", "invalid original challenge", "authorization_binding");
+        const life = new AbortController();
+        const signal = o.signal ? AbortSignal.any([o.signal, life.signal]) : life.signal;
+        const epoch = this.epoch;
+        const check = () => { if (signal.aborted)
+            throw mdbaseError("cancelled", "authorization fenced", "authorization_cancelled"); if (epoch !== this.epoch)
+            throw grantChanged(); };
+        check();
+        const registration = await this.register();
+        const compiled = compileApplicationManifest(this.declaration);
+        const identity = await this.identity();
+        const grantAgreement = await p256Pair(["deriveBits"], "ECDH");
+        const grantSigning = await p256Pair(["sign"], "ECDSA");
+        const noise = await noisePair();
+        const verifier = b64u(random(32));
+        const challenge = b64u(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+        const state = b64u(random(24));
+        const authorizationId = crypto.randomUUID();
+        const issued = new Date();
+        const binding = {
+            protocol_version: APPLICATION_AUTHORIZATION_PROTOCOL_VERSION,
+            authorization_id: authorizationId,
+            application_id: registration.id,
+            application_declaration_id: String(compiled.manifest.id),
+            application_manifest_digest: registration.manifestDigest,
+            application_installation_id: await applicationInstallationIdFromPublicKey(identity.publicKey),
+            installation_signing_public_key: identity.publicKey,
+            grant_agreement_public_key: grantAgreement.publicKey,
+            grant_signing_public_key: grantSigning.publicKey,
+            flow: "authorization_code",
+            authorization_nonce: o.authorizationNonce ?? b64u(random(32)),
+            issued_at: issued.toISOString(),
+            expires_at: new Date(issued.getTime() + 10 * 60_000).toISOString(),
+            redirect_uri: this.redirect.href,
+            state,
+            code_challenge: challenge,
+            contracts: compiled.contracts,
+            requested_operations: [...compiled.operations],
+            ...(compiled.files ? { requested_files: compiled.files } : {}),
+            ...(o.collection ? { collection_id: o.collection } : {}),
+        };
+        const proof = { binding, signature: b64u(await signP256(identity.privateKey, authorizationSigningMessage(binding))) };
+        const keyMessage = concat(NOISE_KEY_DOMAIN, u32(16), uuidToBytes(authorizationId), u32(32), noise.publicKey);
+        const clientNoiseKey = { public_key: b64u(noise.publicKey), signature: b64u(await signP256(grantSigning.privateKey, keyMessage)) };
+        check();
+        const started = await this.request("/oauth/authorization_request", {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                client_id: registration.id,
+                redirect_uri: this.redirect.href,
+                code_challenge: challenge,
+                code_challenge_method: "S256",
+                state,
+                operations: compiled.operations.join(","),
+                ...(o.collection ? { collection_id: o.collection } : {}),
+                application_authorization: JSON.stringify(proof),
+                client_noise_key: JSON.stringify(clientNoiseKey),
+            }),
+        }, signal);
+        check();
+        const uri = started.body?.authorization_uri;
+        if (started.status !== 200 || started.body?.authorization_id !== authorizationId || typeof uri !== "string"
+            || !uri.startsWith(`${this.cpOrigin}/oauth/authorize?`)) {
+            throw mdbaseError("unavailable", `authorization could not be started (${started.status})`, "authorization_start");
+        }
+        // Listen BEFORE attaching this request to the chooser: the normal callback
+        // may arrive before finish is invoked. Keep original state/keys/PKCE only.
+        let popup = null;
+        const callback = this.awaitCallback(state, { navigate() { }, close() { }, get closed() { return popup?.closed === true; } }, { popup: { navigate() { }, close() { } }, signal, timeoutMs: o.timeoutMs });
+        void callback.catch(() => { });
+        let consumed = false;
+        return Object.freeze({ applicationId: registration.id, manifestDigest: registration.manifestDigest, authorizationId, authorizationUri: uri,
+            cancel: () => life.abort(),
+            finish: async (finish) => {
+                finish = Object.freeze({ ...finish });
+                if (consumed)
+                    throw mdbaseError("invalid_request", "original authorization already consumed", "authorization_binding");
+                consumed = true;
+                popup = finish.popup;
+                const abort = () => life.abort();
+                finish.signal?.addEventListener("abort", abort, { once: true });
+                if (finish.signal?.aborted)
+                    life.abort();
+                try {
+                    check();
+                    const collection = finish.collection ?? o.collection;
+                    if (collection !== undefined && !UUID.test(collection))
+                        throw mdbaseError("invalid_request", "invalid approved collection", "authorization_binding");
+                    if (o.collection && collection !== o.collection)
+                        throw mdbaseError("forbidden", "a different collection was approved", "collection_mismatch");
+                    if (o.expectedAccountId && !collection)
+                        throw mdbaseError("invalid_request", "original Private choice required", "authorization_binding");
+                    const code = await callback;
+                    check();
+                    const exchanged = await this.request("/oauth/token", {
+                        method: "POST",
+                        headers: { "content-type": "application/x-www-form-urlencoded" },
+                        body: new URLSearchParams({ grant_type: "authorization_code", code, client_id: registration.id, redirect_uri: this.redirect.href, code_verifier: verifier }),
+                    }, signal);
+                    check();
+                    const nativeCompletion = o.expectedAccountId ? nativeCompletionFromToken(exchanged.body, {
+                        accountId: o.expectedAccountId, authorizationRequestId: authorizationId,
+                        applicationId: registration.id, declarationId: binding.application_declaration_id,
+                        manifestDigest: registration.manifestDigest, applicationInstallationId: binding.application_installation_id,
+                        applicationOrigin: this.redirect.origin, collectionId: collection,
+                        grantSigningPublicKey: grantSigning.publicKey, clientNoisePublicKey: b64u(noise.publicKey),
+                    }) : undefined;
+                    const collectionId = await this.saveTokens(exchanged, { noise, signing: grantSigning.privateKey, collection, check });
+                    check();
+                    return { collectionId, ...(nativeCompletion ? { nativeCompletion } : {}) };
+                }
+                finally {
+                    finish.signal?.removeEventListener("abort", abort);
+                    life.abort();
+                }
+            },
+        });
+    }
+    awaitCallback(state, popup, o) {
+        const timeoutMs = Math.min(Math.max(o.timeoutMs ?? 10 * 60_000, 1_000), 30 * 60_000);
+        return new Promise((resolve, reject) => {
+            let closedSince = null;
+            const finish = (f) => { unsubscribe(); clearTimeout(timer); clearInterval(watch); o.signal?.removeEventListener("abort", abort); f(); };
+            const abort = () => finish(() => reject(mdbaseError("cancelled", "authorization cancelled", "authorization_cancelled")));
+            const unsubscribe = this.callbacks.subscribe((raw) => {
+                let url;
+                try {
+                    url = new URL(raw);
+                }
+                catch {
+                    return;
+                }
+                if (url.origin !== this.redirect.origin || url.pathname !== this.redirect.pathname || url.searchParams.get("state") !== state)
+                    return;
+                const error = url.searchParams.get("error");
+                if (error)
+                    return finish(() => reject(mdbaseError("forbidden", "access was not approved", "authorization_denied")));
+                const code = url.searchParams.get("code");
+                if (!code)
+                    return finish(() => reject(mdbaseError("unavailable", "the authorization callback has no code", "authorization_callback")));
+                finish(() => resolve(code));
+            });
+            const timer = setTimeout(() => finish(() => reject(mdbaseError("cancelled", "authorization timed out", "authorization_timed_out"))), timeoutMs);
+            // A closed popup ends the wait after a short grace for its final callback.
+            const watch = setInterval(() => {
+                let closed = false;
+                try {
+                    closed = popup.closed === true;
+                }
+                catch {
+                    closed = false;
+                }
+                if (!closed) {
+                    closedSince = null;
+                    return;
+                }
+                closedSince ??= Date.now();
+                if (Date.now() - closedSince >= 3_000)
+                    finish(() => reject(mdbaseError("cancelled", "the authorization window was closed", "authorization_cancelled")));
+            }, 500);
+            o.signal?.addEventListener("abort", abort, { once: true });
+            if (o.signal?.aborted)
+                abort();
+        });
+    }
+    async saveTokens(res, from) {
+        const b = res.body;
+        if (res.status !== 200 || !b) {
+            if (res.status === 400 && b && typeof b.error === "string" && b.error === "invalid_grant") {
+                throw mdbaseError("unauthenticated", "the grant is no longer valid", "grant_invalid");
+            }
+            if (res.status === 400)
+                throw collectionUnavailableError("sync_required");
+            throw mdbaseError("unavailable", `token request failed (${res.status})`, "token_error");
+        }
+        const access = b.access_token, refresh = b.refresh_token, collection = b.collection_id;
+        const expiresIn = b.expires_in, refreshExpiresIn = b.refresh_expires_in;
+        if (typeof access !== "string" || typeof refresh !== "string" || typeof collection !== "string" || !UUID.test(collection)
+            || typeof expiresIn !== "number" || !(expiresIn > 0) || typeof refreshExpiresIn !== "number" || !(refreshExpiresIn > 0)) {
+            throw mdbaseError("unavailable", "invalid token response", "token_response");
+        }
+        const id = collection.toLowerCase();
+        if (from.collection && from.collection.toLowerCase() !== id)
+            throw mdbaseError("forbidden", "a different collection was approved", "collection_mismatch");
+        if (from.previous && from.previous.collection !== id)
+            throw mdbaseError("unavailable", "the token names another collection", "token_response");
+        const refreshKey = from.previous?.refreshKey
+            ?? (await crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]));
+        const iv = random(12);
+        const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData: this.aad(id) }, refreshKey, new TextEncoder().encode(refresh)));
+        const noise = from.noise ?? { privateKey: from.previous.noisePrivateKey, publicKey: from.previous.noisePublicKey };
+        const signing = from.signing ?? from.previous?.signingPrivateKey;
+        const next = {
+            version: 1, collection: id, noisePrivateKey: noise.privateKey, noisePublicKey: noise.publicKey,
+            refreshKey, refresh: concat(iv, sealed), refreshExpiresAt: Date.now() + refreshExpiresIn * 1000,
+            ...(signing ? { signingPrivateKey: signing } : {}),
+            ...(from.previous?.owner ? { owner: from.previous.owner } : {}),
+        };
+        const epoch = this.epoch;
+        await this.withLock(id, "commit", async () => {
+            const store = await this.store();
+            if (epoch !== this.epoch)
+                throw grantChanged();
+            if (from.previous && !sameRevision(from.previous, await store.getGrant(id)))
+                throw grantChanged();
+            from.check?.();
+            await store.putGrant(next);
+            const written = await store.getGrant(id);
+            if (!written || !equalBytes(next.noisePublicKey, written.noisePublicKey) || !equalBytes(next.refresh, written.refresh))
+                throw grantChanged();
+            // Commit and cache publication share the writer lock. The cache's original
+            // identity is also checked on every use (including after another tab writes).
+            from.check?.();
+            this.tokens.set(id, { access, expiresAt: Date.now() + expiresIn * 1000, collection: id, owner: written.owner, noisePublicKey: written.noisePublicKey.slice() });
+            this.forgotten.delete(id);
+        });
+        return id;
+    }
+    aad(collection) {
+        return new TextEncoder().encode(`mdbase.app-grant.v2\0${this.cpOrigin}\0${this.owner()}\0${collection}`);
+    }
+    /** A current access token for the collection's grant, refreshing when needed. */
+    async accessToken(collection, force = false) {
+        const grant = await this.heldGrant(collection);
+        const cached = this.tokens.get(collection);
+        if (!force && cached && sameGrant(grant, cached) && cached.expiresAt - Date.now() > 60_000)
+            return cached.access;
+        const running = this.refreshing.get(collection);
+        if (running && sameRevision(grant, running.grant)) {
+            const token = await running.work;
+            await this.assertCurrent(grant);
+            return token;
+        }
+        const work = this.withLock(collection, "refresh", async () => {
+            const current = await this.assertCurrent(grant);
+            return this.refresh(collection, current);
+        });
+        const pending = { grant, work };
+        this.refreshing.set(collection, pending);
+        try {
+            const token = await work;
+            await this.assertCurrent(grant);
+            return token;
+        }
+        finally {
+            if (this.refreshing.get(collection) === pending)
+                this.refreshing.delete(collection);
+        }
+    }
+    // Network refresh serialization is separate from the short commit lock, so
+    // explicit consent can commit while an old network response is held.
+    withLock(collection, kind, f) {
+        // Original local declaration, not a network/registration alias. This broader
+        // namespace also lets a fresh custom-store owner forget keys while offline.
+        return exclusive(`mdbase.app-grant.${kind}:${JSON.stringify([this.cpOrigin, this.owner(), collection])}`, f);
+    }
+    async heldGrant(collection) {
+        const grant = await (await this.store()).getGrant(collection);
+        if (!grant)
+            throw collectionUnavailableError("sync_required");
+        return { ...grant, noisePublicKey: grant.noisePublicKey.slice(), refresh: grant.refresh.slice() };
+    }
+    async assertCurrent(grant) {
+        const current = await (await this.store()).getGrant(grant.collection);
+        if (!sameGrant(grant, current))
+            throw grantChanged();
+        return current;
+    }
+    async refresh(collection, grant) {
+        if (grant.refreshExpiresAt <= Date.now())
+            throw collectionUnavailableError("sync_required");
+        let refresh;
+        try {
+            const plain = await crypto.subtle.decrypt({ name: "AES-GCM", iv: grant.refresh.slice(0, 12), additionalData: this.aad(collection) }, grant.refreshKey, grant.refresh.slice(12));
+            refresh = new TextDecoder().decode(plain);
+        }
+        catch {
+            throw mdbaseError("unauthenticated", "the stored grant could not be read", "grant_storage");
+        }
+        const registration = await this.register();
+        // Connect checks this field order when it verifies the proof over the body.
+        const body = new URLSearchParams({ grant_type: "refresh_token", refresh_token: refresh, client_id: registration.id });
+        // The grant's proof key is its signing key: Connect refuses an unsigned refresh.
+        const proof = grant.signingPrivateKey ? await authorityProof(grant.signingPrivateKey, "/oauth/token", body.toString(), refresh) : {};
+        const res = await this.request("/oauth/token", {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", ...proof },
+            body,
+        });
+        try {
+            await this.saveTokens(res, { previous: grant });
+        }
+        catch (e) {
+            // A refused refresh token will never work again: forget the grant locally.
+            if (isMdbaseError(e, "unauthenticated") && e.reason === "grant_invalid") {
+                await this.withLock(collection, "commit", async () => {
+                    const store = await this.store();
+                    if (!sameRevision(grant, await store.getGrant(collection)))
+                        throw grantChanged();
+                    await store.deleteGrant(collection);
+                    this.forgotten.add(collection);
+                    const cached = this.tokens.get(collection);
+                    if (cached && sameGrant(grant, cached))
+                        this.tokens.delete(collection);
+                });
+            }
+            throw e;
+        }
+        // Never read a newer consent's cache as the result of this older refresh.
+        return res.body.access_token;
+    }
+    /** Fetch the route; one forced refresh on 401. */
+    async route(collection, signal) {
+        for (let attempt = 0;; attempt++) {
+            const token = await this.accessToken(collection, attempt > 0);
+            const res = await this.request(`/v1/next/collections/${encodeURIComponent(collection)}/route`, { headers: { authorization: `Bearer ${token}` } }, signal);
+            if (res.status === 401 && attempt === 0)
+                continue;
+            if (res.status === 401)
+                throw mdbaseError("unauthenticated", "the control plane refused the access token");
+            if (res.status === 409)
+                throw mdbaseError("unauthenticated", "this app's key is not registered with its grant", "client_key_required");
+            if (res.status !== 200 || !res.body)
+                throw mdbaseError("unavailable", `control plane answered ${res.status}`, "control_error");
+            const route = res.body;
+            if (typeof route.collection !== "string" || route.collection.toLowerCase() !== collection || !Array.isArray(route.targets)) {
+                throw mdbaseError("unauthenticated", "the route does not match this collection's grant", "route_mismatch");
+            }
+            const parsed = parseCollectionAvailability(route.availability);
+            const availability = parsed ?? (orderTargets(route, null).length
+                ? { state: "available" } : { state: "unavailable", reason: route.reason === "no_device_registered" ? "no_device_registered" : "device_offline" });
+            return { token, route, availability };
+        }
+    }
+    /** Private collections this app has a grant for, with their availability. */
+    async verifiedStoredNativeGrant(completion) {
+        const registration = await this.register(), grant = await (await this.store()).getGrant(completion.collection_id);
+        return !!grant && completion.application_id === registration.id && completion.application_origin === this.declaration.origin && grant.owner === this.owner() && b64u(grant.noisePublicKey) === completion.client_noise_public_key;
+    }
+    async collections(options = {}) {
+        const records = await (await this.store()).listGrants();
+        const local = [];
+        for (const record of records) {
+            if (options.bindings === undefined || options.bindings.some(c => c.collection_id === record.collection && c.application_origin === this.declaration.origin && b64u(record.noisePublicKey) === c.client_noise_public_key))
+                local.push(record);
+        }
+        const held = new Set(local.map((g) => g.collection));
+        for (const grant of local) {
+            let token;
+            try {
+                token = await this.accessToken(grant.collection);
+            }
+            catch (e) {
+                if (isMdbaseError(e) && ((e.code === "unauthenticated" && e.reason === "grant_invalid") || (e.code === "forbidden" && e.reason === "sync_required")))
+                    continue;
+                throw e; // Failed/cancelled inventory is never an empty COMPLETE inventory.
+            }
+            await this.assertCurrent(grant);
+            const res = await this.request("/v1/next/apps/collections", { headers: { authorization: `Bearer ${token}` } }, options.signal);
+            await this.assertCurrent(grant);
+            if (res.status === 401) {
+                await this.withLock(grant.collection, "commit", async () => {
+                    await this.assertCurrent(grant);
+                    const cached = this.tokens.get(grant.collection);
+                    if (cached?.access !== token || !sameGrant(grant, cached))
+                        throw grantChanged();
+                    this.tokens.delete(grant.collection);
+                });
+                // A rejected access token is failed metadata, not proof the grant ended.
+                throw mdbaseError("unauthenticated", "the control plane refused the collection listing token");
+            }
+            if (res.status !== 200 || !Array.isArray(res.body?.collections))
+                throw mdbaseError("unavailable", `control plane answered ${res.status}`, "control_error");
+            const out = [];
+            for (const raw of res.body.collections) {
+                const id = typeof raw.collection === "string" ? raw.collection.toLowerCase() : "";
+                if (!UUID.test(id) || out.some((c) => c.collectionId === id))
+                    continue;
+                const parsed = parseCollectionAvailability(raw.availability);
+                if (raw.state !== "synced_e2e" && !parsed)
+                    continue; // other collections open through the installation
+                const availability = !held.has(id)
+                    ? { state: "unavailable", reason: "sync_required" } // no key in this browser
+                    : parsed ?? { state: "opening" }; // the grant is still being published to the collection
+                out.push(Object.freeze({
+                    collectionId: id,
+                    displayName: typeof raw.name === "string" ? raw.name : "Collection",
+                    operations: Object.freeze(Array.isArray(raw.operations) ? raw.operations.filter((x) => typeof x === "string") : []),
+                    availability: Object.freeze(availability),
+                    role: ROLES.has(raw.role) ? raw.role : null,
+                }));
+            }
+            return out;
+        }
+        return [];
+    }
+    /** The collection's availability now, from its route. Never throws for `unavailable`. */
+    async availability(collection, options = {}) {
+        const id = collection.toLowerCase();
+        try {
+            return (await this.route(id, options.signal)).availability;
+        }
+        catch (e) {
+            if (isMdbaseError(e) && e.details instanceof Map && typeof e.details.get("availability") === "string") {
+                return parseCollectionAvailability({ state: "unavailable", reason: e.details.get("availability") });
+            }
+            throw e;
+        }
+    }
+    /**
+     * Wait, bounded, until the collection is available: e.g. while the person opens
+     * the desktop app or approves this app there. Resolves with the last availability
+     * (still `unavailable` on timeout); never waits on `sync_required` or `access_removed`.
+     */
+    async waitForAvailable(collection, o = {}) {
+        const deadline = Date.now() + Math.min(Math.max(o.timeoutMs ?? 60_000, 0), 10 * 60_000);
+        const interval = Math.max(o.intervalMs ?? 3_000, 1_000);
+        let last = null;
+        for (;;) {
+            if (o.signal?.aborted)
+                throw mdbaseError("cancelled", "wait cancelled");
+            const now = await this.availability(collection, o.signal ? { signal: o.signal } : {});
+            if (!last || now.state !== last.state || (now.state === "unavailable" && last.state === "unavailable" && now.reason !== last.reason))
+                o.onAvailability?.(now);
+            last = now;
+            if (now.state === "available" || (now.state === "unavailable" && (now.reason === "sync_required" || now.reason === "access_removed")))
+                return now;
+            const left = deadline - Date.now();
+            if (left <= 0)
+                return now;
+            await new Promise((resolve) => {
+                const t = setTimeout(done, Math.min(interval, left));
+                function done() { clearTimeout(t); o.signal?.removeEventListener("abort", done); resolve(); }
+                o.signal?.addEventListener("abort", done, { once: true });
+            });
+        }
+    }
+    /**
+     * A connector for `connect()`: every (re)connect resolves the route, refuses an
+     * unavailable collection with its reason, and opens a Noise IK session through the
+     * relay to a serving device (sticky while it stays listed). The first open pins
+     * its original consent/key identity; new consent requires a new connector.
+     */
+    connector(collection) {
+        const id = collection.toLowerCase();
+        if (!UUID.test(id))
+            throw mdbaseError("invalid_request", "collection must be a UUID");
+        let sticky = null;
+        const webSocket = this.options.webSocket;
+        let original;
+        return registerNextRelayFence({
+            description: `app-grant:${id}`,
+            open: async (hello, signal) => {
+                const grant = await (original ??= this.heldGrant(id));
+                await this.assertCurrent(grant);
+                const connector = noiseConnector({
+                    description: `app-grant:${id}`,
+                    staticKey: staticKeyOf(grant),
+                    target: async (s) => {
+                        await this.assertCurrent(grant);
+                        const { token, route, availability } = await this.route(id, s);
+                        await this.assertCurrent(grant);
+                        if (availability.state === "unavailable")
+                            throw collectionUnavailableError(availability.reason);
+                        if (!UUID.test(route.grant))
+                            throw mdbaseError("unauthenticated", "the route names no grant", "route_mismatch");
+                        const target = orderTargets(route, sticky)[0];
+                        if (!target)
+                            throw collectionUnavailableError("device_offline");
+                        const remoteStatic = new Uint8Array(32);
+                        for (let i = 0; i < 32; i++)
+                            remoteStatic[i] = parseInt(target.noise_pk.slice(2 * i, 2 * i + 2), 16);
+                        return {
+                            prologue: clientPrologue(uuidToBytes(target.relay_collection), uuidToBytes(route.grant), uuidToBytes(target.device)),
+                            remoteStatic,
+                            device: target.device,
+                            openCarrier: async (carrierSignal) => {
+                                await this.assertCurrent(grant);
+                                const carrier = await relayPipeCarrier(target.url, {
+                                    accessToken: token, collection: target.relay_collection, grant: route.grant, device: target.device, devicePublicKey: remoteStatic,
+                                }, webSocket, carrierSignal);
+                                try {
+                                    await this.assertCurrent(grant);
+                                    return carrier;
+                                }
+                                catch (e) {
+                                    carrier.close();
+                                    throw e;
+                                }
+                            },
+                        };
+                    },
+                });
+                const opened = await connector.open(hello, signal);
+                try {
+                    await this.assertCurrent(grant);
+                }
+                catch (e) {
+                    opened.port.close();
+                    throw e;
+                }
+                bindOriginalAppGrant(opened.port, grant);
+                sticky = opened.device ?? null;
+                return opened;
+            },
+            get target() { return sticky; },
+        });
+    }
+    /**
+     * People metadata and Person records for a Private collection: the same
+     * `MdbasePeopleClient` as cloud copies, over `client` (opened with
+     * `connector(collection)`) and Connect's people metadata for this grant. Until a
+     * computer approves the app, metadata fails with availability `approval_required`.
+     */
+    people(collection, client) {
+        const id = collection.toLowerCase();
+        if (!UUID.test(id))
+            throw mdbaseError("invalid_request", "collection must be a UUID");
+        return new MdbasePeopleClient(client, appGrantPeopleAuthority(id, {
+            cpOrigin: this.cpOrigin,
+            fetch: this.fetcher,
+            accessToken: (c, force) => this.accessToken(c, force),
+            holds: (c) => !this.forgotten.has(c),
+        }));
+    }
+    /**
+     * Setup and readiness for a Private collection, over `client` (opened with
+     * `connector(collection)`): the same plan, review wording and guarded apply as
+     * a hosted collection's setup. Native verifies and plans the original signed
+     * declaration; the SDK retains an encrypted original MID before apply and
+     * reconciles receipts without replaying resource operations.
+     */
+    setup(client) {
+        const compiled = compileApplicationManifest(this.declaration);
+        let original;
+        const grant = async () => {
+            const session = client.currentSession(), held = session && originalAppGrant(session);
+            if (!held || held.collection !== client.collection)
+                throw grantChanged();
+            original ??= held;
+            if (!sameGrant(original, held))
+                throw grantChanged();
+            return original;
+        };
+        const assertCurrent = async () => this.assertCurrent(await grant());
+        return privateCollectionSetup({
+            assertCurrent,
+            journal: protectedSetupJournal({ store: () => this.store(), grant, assertCurrent: g => this.assertCurrent(g), aad: this.aad(client.collection) }),
+            client, manifest: compiled.manifest, operations: compiled.operations,
+        });
+    }
+    /** Forget a grant in this browser (its keys and refresh token). Does not revoke it at Connect. */
+    async forget(collection, options = {}) {
+        const id = collection.toLowerCase(), expected = options.expectedNoisePublicKey;
+        await this.withLock(id, "commit", async () => {
+            const store = await this.store(), current = await store.getGrant(id);
+            if (expected !== undefined && current && b64u(current.noisePublicKey) !== expected)
+                throw grantChanged();
+            await store.deleteGrant(id);
+            this.forgotten.add(id);
+            this.tokens.delete(id);
+        });
+    }
+    /**
+     * Sign-out: wipe EVERY grant this browser holds (and their Native setup
+     * attempts), not just ones a caller listed. Grants carry no account, so
+     * anything left behind could be used while a different account is signed
+     * in on a shared browser. The app identity stays (it is the app's
+     * registration, not account authority). Idempotent and safe to run from
+     * several tabs at once; throws when the wipe could not complete, so the
+     * caller can tell the person some local data remains.
+     *
+     * Race safety: the epoch bump fences authorizations and token commits
+     * prepared before the wipe; the wipe then clears the store while holding
+     * every known grant's commit lock (sorted, the same order in every tab),
+     * so a refresh committing at that moment either lands first and is wiped,
+     * or runs after and fails its revision/epoch check instead of re-saving.
+     */
+    async forgetAllGrants() {
+        this.epoch++;
+        const store = await this.store();
+        let ids = [];
+        // The list only picks the locks; clearGrants below is the authority.
+        try {
+            ids = (await store.listGrants()).map(g => g.collection).sort();
+        }
+        catch { /* clearGrants reports */ }
+        for (const id of ids)
+            this.forgotten.add(id);
+        const locked = async (rest, work) => rest.length ? this.withLock(rest[0], "commit", () => locked(rest.slice(1), work)) : work();
+        await locked(ids, async () => {
+            this.tokens.clear();
+            if (typeof store.clearGrants === "function") {
+                await store.clearGrants();
+                return;
+            }
+            // A store built before clearGrants existed: enumerate, delete, prove empty.
+            for (const grant of await store.listGrants()) {
+                await store.deleteGrant(grant.collection);
+                this.forgotten.add(grant.collection);
+            }
+            if ((await store.listGrants()).length)
+                throw mdbaseError("unavailable", "grant storage could not be cleared", "grant_storage");
+        });
+        this.tokens.clear();
+    }
+}
+//# sourceMappingURL=client.js.map