@muhkoo/connect 0.15.0-alpha.10 → 0.15.0-alpha.12

package/dist/connect.workers.d.ts

@@ -1232,6 +1232,310 @@ declare class PaymentRequiredError extends HttpError {
     constructor(message: string, code: PaymentRequiredCode, body?: unknown, upgradeUrl?: string);
 }
 
+/**
+ * Wire types for shared folders. These mirror the accelerator's `/api/shares` JSON
+ * (`ShareInfo` in the accelerator's `durable-objects/space/share.ts`).
+ */
+type ShareKind = "public" | "private";
+/** Who may change a file: `own` = its uploader and the owner; `any` = any member (private shares only). */
+type EditPolicy = "own" | "any";
+interface ShareInfo {
+    kind: ShareKind;
+    ownerUsername: string;
+    /** Storage cap in bytes, or null for no cap. */
+    limitBytes: number | null;
+    usedBytes: number;
+    editPolicy: EditPolicy;
+    name: string;
+    /** Set once the share was rotated into another Space; follow `successor`. */
+    closed: {
+        successor: string;
+        at: number;
+    } | null;
+    /** The member list (usernames). */
+    members: string[];
+    /**
+     * Display names by username, for uploaders and admitted members: label files by their `owner` with it. After a
+     * rotation it also holds uploaders not (yet) re-admitted, so it is not the member list.
+     */
+    names: Record<string, string>;
+}
+/** One row of `GET /api/shares`. */
+interface ShareSummary {
+    spaceId: string;
+    kind: ShareKind;
+    owner: string;
+    name: string;
+}
+/** The password verifier the server stores for a public share (`proof` is derived from it). */
+type PasswordVerifier = {
+    salt: string;
+    iterations: number;
+    verifier: string;
+};
+/** `GET /api/shares/:spaceId/public`: what a guest needs before being admitted (app key only, no session). */
+interface SharePublicInfo {
+    kind: "public";
+    name: string;
+    ownerUsername: string;
+    password: {
+        salt: string;
+        iterations: number;
+    };
+    closed: {
+        successor: string;
+        at: number;
+    } | null;
+}
+interface CreateShareBody {
+    spaceId: string;
+    kind: ShareKind;
+    name: string;
+    limitBytes: number | null;
+    editPolicy: EditPolicy;
+    password?: PasswordVerifier;
+}
+/** `POST /api/shares/:spaceId/admit`, sent with the signed-in account's session. */
+interface ShareAdmitBody {
+    /** `passwordProof(password, salt, iterations)` with the share's public salt and iterations. */
+    proof: string;
+    /** The display name shown next to this member's uploads: 1–40 characters after trimming, no control characters. */
+    name: string;
+}
+
+/**
+ * Typed refusals from the shares API. Each extends {@link HttpError}, so code that only knows `HttpError` still
+ * sees the status and body. Codes are the accelerator's wire contract.
+ */
+
+/** 402 `share_full`: the share is at its storage cap. */
+declare class ShareFullError extends HttpError {
+    readonly limitBytes: number;
+    readonly usedBytes: number;
+    /**
+     * How many items of a `Share.writeMany` were not written (the refused one and every one after it). The
+     * server's body has no such field, so it is 0 on an error straight from the wire.
+     */
+    readonly refused: number;
+    constructor(message: string, limitBytes: number, usedBytes: number, 
+    /**
+     * How many items of a `Share.writeMany` were not written (the refused one and every one after it). The
+     * server's body has no such field, so it is 0 on an error straight from the wire.
+     */
+    refused: number, body?: unknown);
+}
+/** 409 `share_closed`: the share was rotated; use `successor` instead. */
+declare class ShareClosedError extends HttpError {
+    readonly successor: string;
+    constructor(message: string, successor: string, body?: unknown);
+}
+/** 403 `share_password`: wrong password. */
+declare class SharePasswordError extends HttpError {
+    constructor(message: string, body?: unknown);
+}
+/** 429 `share_password_rate`: too many wrong passwords. */
+declare class SharePasswordRateError extends HttpError {
+    readonly retryAfterSeconds: number;
+    constructor(message: string, retryAfterSeconds: number, body?: unknown);
+}
+/** 403 `share_member_limit`: the share holds as many members as it allows. */
+declare class ShareMemberLimitError extends HttpError {
+    constructor(message: string, body?: unknown);
+}
+/** 409 `share_space_not_empty`: only an empty Space can become a share. */
+declare class ShareSpaceNotEmptyError extends HttpError {
+    constructor(message: string, body?: unknown);
+}
+/** 409 `share_space_not_ready`: the Space has no `/metadata` yet; create the Space before making it a share. */
+declare class ShareSpaceNotReadyError extends HttpError {
+    constructor(message: string, body?: unknown);
+}
+/** 409 `rotation_mismatch`: a retried rotation asked for other settings than the one in progress. */
+declare class RotationMismatchError extends HttpError {
+    constructor(message: string, body?: unknown);
+}
+/** 409 `rotation_in_progress`: another rotation of this share won; `successor` is its new Space. */
+declare class RotationInProgressError extends HttpError {
+    readonly successor: string;
+    constructor(message: string, successor: string, body?: unknown);
+}
+/**
+ * A rotation (`changePassword` / `removeMember`) claimed `newSpaceId` but its adopt did not finish (network failure
+ * or server error, retried). It is kept on this device: call the same rotation again, or `shares.resumeRotation`,
+ * to finish it into the SAME Space. No other rotation of this share starts until it does.
+ */
+declare class RotationIncompleteError extends Error {
+    readonly from: string;
+    readonly newSpaceId: string;
+    readonly cause?: unknown | undefined;
+    constructor(from: string, newSpaceId: string, cause?: unknown | undefined);
+}
+/** A guest recovery code that does not parse (expected `<username>:<words>`). */
+declare class InvalidRecoveryCodeError extends Error {
+    constructor(message?: string);
+}
+/** `restoreGuest` would replace another guest's login kept on this device; pass `{ replace: true }` to do so. */
+declare class GuestLoginConflictError extends Error {
+    readonly existing: string;
+    constructor(existing: string);
+}
+/**
+ * The typed error for a refused response, or null when it is not a share refusal (the caller then throws what it
+ * threw before). `body` is the parsed JSON or the raw response text. `retryAfterSeconds` is the `Retry-After`
+ * header, used for a 429.
+ */
+declare function shareErrorFrom(status: number, body: unknown, retryAfterSeconds?: number): Error | null;
+
+/**
+ * `HttpClient` — the one place the unified {@link Client} talks to the
+ * accelerator over HTTP.
+ *
+ * Every request carries two independent credentials:
+ *   - the **app key** (`mk_…`) on `X-Muhkoo-Key` — resolves the app /
+ *     developer / env context the accelerator uses for routing + billing;
+ *   - the **user session token** on `X-Muhkoo-Session` (when a user is
+ *     logged in) — the accelerator validates it and injects a trusted
+ *     `X-Muhkoo-User-Context` downstream so per-user spaces can authorize
+ *     the request without a fresh Groth16 proof.
+ *
+ * `X-Muhkoo-Key` is used (rather than `Authorization: Bearer`) because it is
+ * a non-forbidden header that skips the CORS preflight in browsers.
+ *
+ * The class exposes a header-injecting {@link fetch} that can be handed to
+ * lower-level building blocks (`AuthClient`, `PersonalSpaceClient`) so they
+ * keep owning their own wire shapes while still getting the credentials, plus
+ * convenience JSON helpers (`get`/`post`/`del`) for code that talks to the
+ * accelerator directly.
+ */
+interface HttpClientOptions {
+    /** Absolute URL of the accelerator worker (trailing slash optional). */
+    baseUrl: string;
+    /**
+     * App / publishable key, e.g. `mk_test_pk_…`. Sent on every request as
+     * `X-Muhkoo-Key` when present. Transitionally optional (auth + personal
+     * storage still function without it), but the product direction is to
+     * REQUIRE it — it attributes traffic for billing/metering and authorizes
+     * shared-space (messaging) websockets.
+     */
+    apiKey?: string;
+    /**
+     * A scoped, expiring **access token** (`mk_<env>_at_…`) — the non-ZK
+     * machine-to-machine credential. It resolves through the SAME accelerator
+     * path as an app key and rides the same `X-Muhkoo-Key` header; when present
+     * it takes precedence over {@link apiKey}. Use it for server-side / CI
+     * callers that shouldn't carry the app's publishable key.
+     */
+    accessToken?: string;
+    /** Returns the current user session token, or `null` when logged out. */
+    getSessionToken?: () => string | null;
+    /** Custom fetch — defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /**
+     * Called when a token-gated request comes back `401` (stale/expired
+     * session). Should attempt to silently re-establish a session and resolve
+     * `true` if it succeeded (the request is then retried once with the fresh
+     * token) or `false` if it couldn't (the `401` propagates as an
+     * {@link HttpError}). Wired by {@link Client} to `auth.zk.recover()`.
+     *
+     * Only consulted by the JSON helpers (`get`/`post`/`del`) and
+     * {@link HttpClient.fetchWithRecovery}; the raw {@link fetch} passes 401s
+     * straight through so the auth wire calls that power recovery itself
+     * can't recurse.
+     */
+    onUnauthorized?: () => Promise<boolean>;
+}
+
+declare class HttpClient {
+    readonly baseUrl: string;
+    /** Origin of {@link baseUrl} — credentials are only attached same-origin. */
+    private readonly baseOrigin;
+    private readonly apiKey;
+    /** Scoped machine access token — takes precedence over {@link apiKey} on `X-Muhkoo-Key`. */
+    private readonly accessToken;
+    private readonly getSessionToken;
+    private readonly onUnauthorized;
+    private readonly fetchFn;
+    constructor(opts: HttpClientOptions);
+    /**
+     * A `fetch`-compatible function that injects the app key + session token
+     * headers. Hand this to `AuthClient` / `PersonalSpaceClient` so they pick
+     * up credentials without knowing about them.
+     */
+    readonly fetch: typeof fetch;
+    /**
+     * {@link fetch} with the JSON helpers' stale-session recovery: a 401 on a
+     * request made while a session token is held runs `onUnauthorized` once
+     * and, if that recovered, replays the request once with the fresh token.
+     * The final response is returned whatever its status, never thrown. The
+     * replay re-sends `init` as given, so its body must be re-sendable (a
+     * string or bytes, not a stream).
+     */
+    readonly fetchWithRecovery: typeof fetch;
+    /**
+     * A client for the same accelerator and key that never sends a session token and never recovers one. For routes
+     * that need only the app key (a public share's pre-admission info).
+     */
+    withoutSession(): HttpClient;
+    /** True when `input` resolves to {@link baseOrigin} (relative URLs always do). */
+    private isSameOrigin;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    del<T = unknown>(path: string, body?: unknown): Promise<T>;
+    private request;
+}
+
+/**
+ * `SharesClient` — the thin HTTP layer over the accelerator's `/api/shares` routes. It owns paths, verbs and error
+ * mapping and nothing else; the `Share` object and `client.shares` build on it.
+ *
+ * Every call but `publicInfo` carries the app key and the signed-in session (with the usual stale-session recovery),
+ * including `admit`: a public share's guest is an ordinary account. `publicInfo` needs only the app key and never
+ * sends a session.
+ */
+
+declare class SharesClient {
+    private readonly http;
+    private readonly keyOnlyHttp;
+    constructor(http: HttpClient);
+    create(body: CreateShareBody): Promise<ShareInfo>;
+    list(): Promise<ShareSummary[]>;
+    info(spaceId: string): Promise<ShareInfo>;
+    update(spaceId: string, patch: {
+        limitBytes?: number | null;
+        editPolicy?: EditPolicy;
+    }): Promise<ShareInfo>;
+    /** A public share's name, owner and password salt, read before admission. Publishable key only; never the verifier. */
+    publicInfo(spaceId: string): Promise<SharePublicInfo>;
+    /**
+     * Admit the signed-in account to a public share by proving its password. Afterwards the account is a member:
+     * it sends its own `/keyring/join-request`. Re-admitting the same account only updates its name.
+     */
+    admit(spaceId: string, body: ShareAdmitBody): Promise<void>;
+    removeMember(spaceId: string, username: string): Promise<void>;
+    /** Rotate: `from` is the old share, `newSpaceId` the Space the client made and seeded. */
+    adopt(newSpaceId: string, body: {
+        from: string;
+        password?: PasswordVerifier;
+        remove?: string[];
+    }): Promise<ShareInfo>;
+    private send;
+}
+
+/**
+ * Public-share password proof. The password never leaves the device: the guest sends
+ * `proof = base64(PBKDF2-SHA256(password, salt, iterations, 32 bytes))` and the server stores
+ * `verifier = base64(SHA-256(proof bytes))`. The salt is an opaque string chosen at creation time;
+ * both sides use its UTF-8 bytes.
+ */
+
+declare const SHARE_PASSWORD_ITERATIONS = 310000;
+/** What a guest sends to prove it knows the password. */
+declare function passwordProof(password: string, salt: string, iterations: number): Promise<string>;
+/** What the share owner registers at creation: a fresh salt and the verifier for `password`. */
+declare function newPasswordVerifier(password: string): Promise<PasswordVerifier>;
+
 /**
  * Cloudflare-Workers-compatible Groth16 ZK proof verifier.
  *
@@ -1274,5 +1578,5 @@ declare function initBn128Wasm(wasmModule?: WebAssembly.Module): Promise<Bn128Wa
  */
 declare function verifyGroth16(wasmInstance: WebAssembly.Instance, memory: WebAssembly.Memory, initialPFree: number, verificationKey: VerificationKey, proof: Groth16Proof, publicSignals: string[]): Promise<boolean>;
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, BroadcastChannel, BroadcastChannelEvents, ChunkCipher, DoubleRatchet, EncryptedSession, EventCore, EventCoreEvents, KeyStore, Message, Message as MessageDefault, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PaymentRequiredError, SerializeMessage, WSTransport, decorators, decryptAesGcm, deriveAesKeyFromPassphrase, deriveBitsHkdf, encryptAesGcm, getSubtle, initBn128Wasm, randomBytes, unwrapWithPassphrase, verifyGroth16, wrapWithPassphrase };
-export type { ACL, ACLEntry, AuthKeyPair, AuthType, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChunkKeyMaterial, CipherFrame, CipherMessage, CipherMessageHeader, DehydratedKeypair, DehydratedKeys, ECDHCurve, Groth16Proof, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, MessageBody, MessageEvent, MessageHeaders, MessageOptions, OAuthProvider, PacketOptions, Participant, PaymentRequiredCode, Permission, PermissionCheckRequest, PermissionCheckResult, PublicKeyJWK, RatchetState, ReceiveResult, Role, Session, SessionOptions, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, BroadcastChannel, BroadcastChannelEvents, ChunkCipher, DoubleRatchet, EncryptedSession, EventCore, EventCoreEvents, GuestLoginConflictError, InvalidRecoveryCodeError, KeyStore, Message, Message as MessageDefault, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PaymentRequiredError, RotationInProgressError, RotationIncompleteError, RotationMismatchError, SHARE_PASSWORD_ITERATIONS, SerializeMessage, ShareClosedError, ShareFullError, ShareMemberLimitError, SharePasswordError, SharePasswordRateError, ShareSpaceNotEmptyError, ShareSpaceNotReadyError, SharesClient, WSTransport, decorators, decryptAesGcm, deriveAesKeyFromPassphrase, deriveBitsHkdf, encryptAesGcm, getSubtle, initBn128Wasm, newPasswordVerifier, passwordProof, randomBytes, shareErrorFrom, unwrapWithPassphrase, verifyGroth16, wrapWithPassphrase };
+export type { ACL, ACLEntry, AuthKeyPair, AuthType, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChunkKeyMaterial, CipherFrame, CipherMessage, CipherMessageHeader, CreateShareBody, DehydratedKeypair, DehydratedKeys, ECDHCurve, EditPolicy, Groth16Proof, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, MessageBody, MessageEvent, MessageHeaders, MessageOptions, OAuthProvider, PacketOptions, Participant, PasswordVerifier, PaymentRequiredCode, Permission, PermissionCheckRequest, PermissionCheckResult, PublicKeyJWK, RatchetState, ReceiveResult, Role, Session, SessionOptions, ShareAdmitBody, ShareInfo, ShareKind, SharePublicInfo, ShareSummary, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload };