@mdbase-dev/sdk 0.1.0-beta.168 → 0.1.0-beta.173

package/README.md

@@ -375,6 +375,72 @@ Not covered yet for Private collections:
   report it: older servers, or an account whose access needs renewing. Gate
   owner actions on `role === "owner"`; Connect still checks each action.
 
+## Private collections on the app's own replica
+
+An app that hosts its own replica through `MdbaseApplication` (`createMdbase`)
+can open an existing Private collection with that replica, as a device of the
+collection, instead of through the relay. The person unlocks it once with the
+account's encryption password or recovery key. Connect only offers this to
+apps it allows to hold a Private key.
+
+- **Ask for it.** List `offline.replica` in the declaration's capabilities,
+  under `requirements.capabilities.optional` or `required`. Prefer `optional`:
+  the app then still signs in and syncs cloud copies where device access is not
+  offered, and consent for an app grant on a current account refuses an app
+  that lists it as required. The sign-in request asks for device access
+  (`requested_private_device`), and the person chooses which Private
+  collections to share. A server that does not know the request is asked again
+  without it, and one that does not offer device access to this app answers
+  with no Private collections; both leave an ordinary cloud-copy sign-in. An
+  installation paired before this needs to ask for access again.
+- **List.** Entries in `snapshot.collections` carry `mode: "private"`; absent
+  means a cloud copy. A server from before this feature (after a rollback)
+  answers the list without modes; the SDK then asks once more with the earlier
+  request, so file actions are kept and no Private entry is listed.
+- **Open.** `select(id)` as usual. An approval that shares only Private
+  collections names no selected collection, so the app arrives in its chooser;
+  when exactly one collection is approved the application opens it by itself,
+  as it does a sole cloud copy. A device that already holds the key goes
+  straight to `ready`. One that doesn't reads
+  `{kind: "needs_unlock", collectionId, displayName, mode, unlocking, problem}`.
+  There is no `connection` while locked.
+- **Unlock.** For `mode: "password"`, call
+  `mdbase.unlock(collectionId, {password})` or `{recoveryKey}` with what the
+  person typed, and keep no copy. It resolves when the attempt has settled: the
+  collection continues to `ready` (or `needs_setup`) without a reload, or the
+  phase is still `needs_unlock` with `problem` set. `problem` is an
+  `MdbaseProblem` with its copy already described; its `key` is one of
+  `wrong_secret`, `invalid_recovery_key`, `rate_limited`, `unavailable`,
+  `unlock_unavailable` or `unlock_failed`. `mode: "strict"`
+  and `mode: "none"` cannot be unlocked here: explain that this collection has
+  to be opened on a computer running the mdbase app.
+- **Retries.** Connect limits how often an account's sealed key can be fetched
+  (10 an hour, shared by all of the account's devices; `rate_limited` carries
+  the wait). A mistyped recovery key (`invalid_recovery_key`) and a password
+  shorter than the 12-character minimum (`wrong_secret`) are refused in the
+  Worker without any request. After a wrong secret the Worker keeps the sealed
+  bundle in memory for the next attempt on the same locked collection, and
+  uses it only while Connect's status still reports the same account key
+  version; it is dropped when the collection unlocks or closes.
+- **Afterwards.** Once the unlock has applied, reopening needs no secret. A
+  restart before it applied returns to `needs_unlock`.
+
+The password or recovery key is sent to the Worker as bytes that are wiped in
+the tab as soon as they are posted and in the Worker when the call settles. The
+key it unlocks is used once and wiped; neither is stored. One installation can
+be a device of one Private collection (`private_device_limit` for a second),
+and People is not available for these collections yet: `connection.people`
+is present, and its reads reject with `upgrade_required`
+(`people_unsupported`).
+
+To fetch the sealed account key, the app runtime signs one fixed request: the
+account-key fetch proof for its own connector and device, over the server's
+challenge and the signed-in account. It signs nothing else for the account key
+(no change, no strict approval, no caller-chosen digest), and the fetched
+bundle is still sealed under the person's password or recovery key, which both
+kinds of unlock need. An older app runtime without this signer answers
+`unlock_unavailable`, and the collection stays `needs_unlock`.
+
 ## Managed application build environments
 
 Application declarations support explicit `lab`, `staging` and `production`
@@ -383,9 +449,31 @@ trust handoff for that exact environment; changing an app build variable cannot
 retarget a LAB archive. Staging packaging pins Connect to
 `https://connect-staging.mdbase.dev`, production to `https://connect.mdbase.dev`.
 CP/log origins and release trust still come only from the verified build context;
-missing, expired or crossed trust refuses without a fallback. Staging and
-production do not permit HTTP loopback app origins. Isolated `local` builds remain
-separate and refuse all managed environments.
+missing, expired or crossed trust refuses without a fallback. Isolated `local`
+builds remain separate and refuse all managed environments.
+
+### Developing on localhost
+
+In every managed environment the app's own `origin` may be a loopback HTTP
+origin (`http://localhost:<port>`, `http://127.0.0.1:<port>` or
+`http://[::1]:<port>`), so an app is developed against production with the
+published package:
+
+```ts
+createMdbase({ id, name, origin: "http://localhost:5173", environment: "production", manifest: devManifest });
+```
+
+The manifest's `homepage` and `redirect_uris` use that same origin. Connect
+registers it as its own application, apart from the one published at the HTTPS
+origin: approvals and device storage belong to the exact origin and are not
+shared between the two. The approval screen calls it "an app running on this
+computer" and says its identity is unverified, as it does for a native app.
+Connect's own origins (control plane, log) stay HTTPS outside LAB; no other
+plain-HTTP app origin is accepted.
+
+`vite dev` and `vite build` both work with Vite's default configuration: the
+SDK's worker and WebAssembly files are served from `node_modules` in
+development and emitted as assets in a build.
 
 The app manifest must declare the installation origin under
 `installation_origins.staging` for staging pairing, just as for other environments.

package/dist/app-host/account-key-host.d.ts

@@ -0,0 +1,128 @@
+import { type Argon2idRunner } from "../account-key.js";
+import { type AccountKeyControlPort, type AccountKeyMode, type PrivateAccountRequestOptions } from "../private-account.js";
+import { type AppAccountKeyState } from "./wasm-runtime.js";
+/** What the person typed. Strings cannot be wiped in JavaScript: callers drop
+ * their references at once and never log, store or publish them. */
+export type AppAccountKeySecret = Readonly<{
+    password: string;
+}> | Readonly<{
+    recoveryKey: string;
+}>;
+/** Why an unlock ended without a keyed device. The collection stays locked and
+ * usable for another attempt; each code has plain copy in `describeError`. */
+export type AppAccountKeyUnlockProblem = 
+/** Wrong encryption password, or a recovery key of another account key. */
+"wrong_secret"
+/** The typed recovery key is not well formed. */
+ | "invalid_recovery_key"
+/** The account has no account key: nothing to unlock with. */
+ | "no_account_key"
+/** The account uses strict device approval: no password unlock exists. */
+ | "unlock_strict" | "rate_limited"
+/** The account key service or the log could not be reached, or answered badly. */
+ | "unavailable"
+/** This app runtime predates the account-key fetch proof signer. */
+ | "unlock_unavailable"
+/** The secret is right, but this collection refused the grant (`detail`). */
+ | "unlock_failed";
+export declare class AppAccountKeyUnlockError extends Error {
+    readonly reason: AppAccountKeyUnlockProblem;
+    readonly detail?: string | undefined;
+    readonly retryAfterMs?: number | undefined;
+    constructor(reason: AppAccountKeyUnlockProblem, detail?: string | undefined, retryAfterMs?: number | undefined);
+}
+/** The authenticated installation session of the adopted Private device. */
+export interface AppAccountKeySession {
+    readonly accountId: string;
+    readonly connectorId: string;
+    readonly deviceId: string;
+    readonly collection: string;
+    readonly cpOrigin: string;
+    isCurrent(): boolean;
+    connectorBearer(options: {
+        signal: AbortSignal;
+    }): Promise<string>;
+}
+/** The native device, narrowed to what an unlock may do. */
+export interface AppAccountKeyNative {
+    /** False when the pinned runtime has no account-key fetch signer. */
+    supportsFetchProof(): boolean;
+    /** The fixed `mdbase/v1/account-key-fetch` proof over a server challenge. */
+    signFetch(challenge: Uint8Array): Uint8Array;
+    /** Consumes and wipes the 32-byte loan on every path. */
+    unlockConsuming(secret: Uint8Array): AppAccountKeyState;
+    status(): AppAccountKeyState;
+    /** One foreground log turn. */
+    drive(options: {
+        signal: AbortSignal;
+    }): Promise<void>;
+    /** The log head the replica knows; 0 until a log turn has succeeded. */
+    headKnown(): number;
+}
+export interface AppAccountKeyHostOptions {
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+    readonly allowLoopbackHttp?: boolean;
+    /** Off-thread Argon2id; the default runs in this Worker. */
+    readonly argon2id?: Argon2idRunner;
+    /** How long a started self-grant may stay pending before the call gives up
+     * (the grant itself is not withdrawn). */
+    readonly settleMs?: number;
+}
+/** The sealed account-key bundle that ONE locked Private collection keeps
+ * between unlock attempts, so a mistyped password or a recovery key of another
+ * account key does not spend the account-wide fetch budget (10 per hour, shared
+ * with the person's other devices) again. It is the ciphertext Connect already
+ * gave this device, held in RAM only: never persisted, published or returned
+ * to the app. A held answer is used only while the budget-free status route,
+ * which applies the same account and installation scope checks on every
+ * attempt, still reports the same account-key version and key id for the same
+ * account, connector and device. Anything else drops it and fetches afresh.
+ * `unlockPrivateDevice` drops it on every outcome but a wrong secret; the
+ * owner clears it when the collection closes (which is also sign-out). */
+export declare class AppAccountKeySealedBundle {
+    private held;
+    /** True while a sealed bundle is held. */
+    get holding(): boolean;
+    clear(): void;
+}
+/** `AccountKeyControlPort` over the installation bearer: status, challenge and
+ * fetch only. One fixed request each, no retry, bounded decoded bodies. */
+export declare class AppCpAccountKeyControl implements AccountKeyControlPort {
+    private readonly session;
+    private readonly sign;
+    readonly accountId: string;
+    private readonly lifetime;
+    private readonly origin;
+    private readonly deviceId;
+    private readonly fetchImpl;
+    private readonly now;
+    constructor(session: AppAccountKeySession, sign: (challenge: Uint8Array) => Uint8Array, options?: AppAccountKeyHostOptions);
+    private check;
+    private request;
+    status(options: PrivateAccountRequestOptions): Promise<unknown>;
+    challenge(options: PrivateAccountRequestOptions): Promise<unknown>;
+    /** A fresh single-use challenge, the native fetch proof over it, then the
+     * bundle. The challenge and signature are wiped here; the bundle is returned
+     * to PrivateAccount only. */
+    fetch(options: PrivateAccountRequestOptions): Promise<unknown>;
+    put(): Promise<unknown>;
+    strict(): Promise<unknown>;
+    enrolRecoveryDevice(): Promise<unknown>;
+    close(): void;
+}
+/** The account-key mode from the status route (no bundle, no proof, not on the
+ * fetch budget). A failed read rejects: the mode is never guessed. */
+export declare function readAccountKeyMode(session: AppAccountKeySession, options: AppAccountKeyHostOptions & {
+    signal: AbortSignal;
+}): Promise<AccountKeyMode>;
+/** Unlock this device's ONE adopted Private collection with the account key.
+ * Resolves only once the native applied policy has this device keyed and
+ * trusted. A typed `AppAccountKeyUnlockError` leaves the collection locked and
+ * open for another attempt; anything else is a lost owner or cancelled call. */
+export declare function unlockPrivateDevice(session: AppAccountKeySession, native: AppAccountKeyNative, secret: AppAccountKeySecret, options: AppAccountKeyHostOptions & {
+    signal: AbortSignal;
+    onMode?(mode: AccountKeyMode): void;
+    /** This locked collection's holder for the sealed bundle between attempts. Without one, every attempt fetches. */
+    sealed?: AppAccountKeySealedBundle;
+}): Promise<void>;