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

package/dist/app-grant/client.d.ts

@@ -0,0 +1,209 @@
+import type { AppInstallationCollection } from "../app-host/installation-sign-in.js";
+import { type MdbaseApplicationDeclaration } from "../application/declaration.js";
+import { type CollectionAvailability } from "../collection-availability.js";
+import { type WebSocketFactory } from "../transport/noise-session.js";
+import type { Connector } from "../transport/port.js";
+import { MdbasePeopleClient } from "../people.js";
+import type { MdbaseClient } from "../client.js";
+import { type MdbasePrivateSetup } from "./setup.js";
+import { type AppGrantStore } from "./grant-store.js";
+import { type NativeCompletion } from "./native-completion.js";
+/** A window the UI reserved synchronously in the user's gesture (`window.open`). */
+export interface AppGrantPopup {
+    navigate(url: string): void;
+    close(): void;
+    /** True once the person closed it. Optional; without it only the timeout applies. */
+    readonly closed?: boolean;
+}
+/** How the redirect page's URL reaches the waiting flow. Default: a same-origin BroadcastChannel. */
+export interface AppGrantCallbackPort {
+    subscribe(listener: (url: string) => void): () => void;
+}
+export interface MdbaseAppGrantsOptions {
+    readonly declaration: MdbaseApplicationDeclaration;
+    /** One of the manifest's `redirect_uris`. That page calls {@link deliverAppGrantCallback}. */
+    readonly redirectUri: string;
+    readonly store?: AppGrantStore;
+    readonly callbacks?: AppGrantCallbackPort;
+    readonly fetch?: typeof fetch;
+    readonly webSocket?: WebSocketFactory;
+}
+export interface MdbaseAuthorizeOptions {
+    readonly popup: AppGrantPopup;
+    /** Ask for this collection only. */
+    readonly collection?: string;
+    readonly signal?: AbortSignal;
+    /** Default 10 minutes, at most 30. */
+    readonly timeoutMs?: number;
+}
+/** Preparation for the SAME popup's ordinary authorization callback. No keys or tokens leave this owner. */
+export interface MdbasePrepareAuthorizationOptions {
+    readonly collection?: string;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    /** Original protected registration challenge, canonical base64url of32 bytes. */
+    readonly authorizationNonce?: string;
+    /** When supplied, original Native completion must prove this account before persistence. */
+    readonly expectedAccountId?: string;
+}
+export interface MdbasePreparedAuthorization {
+    /** Exact original verified registration; the pairing bridge must match its application UUID. */
+    readonly applicationId: string;
+    readonly manifestDigest: string;
+    readonly authorizationId: string;
+    readonly authorizationUri: string;
+    /** Single-use original callback/code/PKCE completion, never a navigation or new request. */
+    finish(options: MdbaseAuthorizeOptions): Promise<{
+        collectionId: string;
+        nativeCompletion?: NativeCompletion;
+    }>;
+    /** Ends the original callback wait; does not close or replace the shared popup. */
+    cancel(): void;
+}
+/** The account's role in a collection; `null` when Connect didn't report one. */
+export type MdbaseCollectionRole = "owner" | "editor" | "viewer";
+/** A Private collection this app has a grant for. */
+export interface MdbasePrivateCollection {
+    readonly collectionId: string;
+    readonly displayName: string;
+    readonly operations: readonly string[];
+    /** Display and UI gating only (e.g. owner actions); Connect checks every action. */
+    readonly role: MdbaseCollectionRole | null;
+    readonly availability: CollectionAvailability;
+}
+/** One entry of the merged list: cloud copies opened by the installation, Private collections by a grant. */
+export interface MdbaseCollectionEntry {
+    readonly collectionId: string;
+    readonly displayName: string;
+    readonly kind: "cloud_copy" | "private";
+    readonly availability: CollectionAvailability;
+    /** The cloud copy's role, or the Private collection's when Connect reported it. */
+    readonly role: MdbaseCollectionRole | null;
+}
+export interface MdbaseWaitOptions {
+    readonly signal?: AbortSignal;
+    /** Default 60 s, at most 10 minutes. */
+    readonly timeoutMs?: number;
+    /** Default 3 s, at least 1 s. */
+    readonly intervalMs?: number;
+    onAvailability?(availability: CollectionAvailability): void;
+}
+/** Call from the redirect page with `location.href`; the waiting flow picks it up. */
+export declare function deliverAppGrantCallback(url: string): void;
+/** Cloud copies from the installation sign-in plus Private collections, by name. */
+export declare function mergeCollectionEntries(cloud: readonly AppInstallationCollection[], privates: readonly MdbasePrivateCollection[]): MdbaseCollectionEntry[];
+/**
+ * Application grants of one app installation (a browser profile) against its
+ * Connect environment. Generic: no app-specific behaviour.
+ */
+export declare class MdbaseAppGrants {
+    private readonly options;
+    private readonly declaration;
+    private readonly cpOrigin;
+    private readonly redirect;
+    private readonly fetcher;
+    private readonly callbacks;
+    private storeValue;
+    private registration;
+    private readonly tokens;
+    private readonly refreshing;
+    private readonly forgotten;
+    /** Bumped by every whole-store wipe: work prepared under an older epoch
+     * (an authorization or token commit racing sign-out) must not re-save. */
+    private epoch;
+    constructor(options: MdbaseAppGrantsOptions);
+    private register;
+    private ownerValue;
+    /**
+     * 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.
+     */
+    private owner;
+    private store;
+    private identity;
+    private request;
+    /**
+     * 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.
+     */
+    authorize(o: MdbaseAuthorizeOptions): Promise<{
+        collectionId: string;
+    }>;
+    prepareAuthorization(o?: MdbasePrepareAuthorizationOptions): Promise<MdbasePreparedAuthorization>;
+    private awaitCallback;
+    private saveTokens;
+    private aad;
+    /** A current access token for the collection's grant, refreshing when needed. */
+    private accessToken;
+    private withLock;
+    private heldGrant;
+    private assertCurrent;
+    private refresh;
+    /** Fetch the route; one forced refresh on 401. */
+    private route;
+    /** Private collections this app has a grant for, with their availability. */
+    verifiedStoredNativeGrant(completion: NativeCompletion): Promise<boolean>;
+    collections(options?: {
+        signal?: AbortSignal;
+        bindings?: readonly NativeCompletion[];
+    }): Promise<MdbasePrivateCollection[]>;
+    /** The collection's availability now, from its route. Never throws for `unavailable`. */
+    availability(collection: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<CollectionAvailability>;
+    /**
+     * 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`.
+     */
+    waitForAvailable(collection: string, o?: MdbaseWaitOptions): Promise<CollectionAvailability>;
+    /**
+     * 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: string): Connector & {
+        readonly target: string | null;
+    };
+    /**
+     * 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: string, client: Pick<MdbaseClient, "queryContract" | "readyForRead" | "currentSession">): MdbasePeopleClient;
+    /**
+     * 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: MdbaseClient): MdbasePrivateSetup;
+    /** Forget a grant in this browser (its keys and refresh token). Does not revoke it at Connect. */
+    forget(collection: string, options?: {
+        readonly expectedNoisePublicKey?: string;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    forgetAllGrants(): Promise<void>;
+}