mindoodb 0.0.50 → 0.0.53

package/dist/core/types.d.ts

@@ -26,12 +26,30 @@ import type { VirtualViewUpdateOptions } from "./indexing/virtualviews/IVirtualV
  * KeyBag location: type "doc", id PUBLIC_INFOS_KEY_ID.
  */
 export declare const PUBLIC_INFOS_KEY_ID = "$publicinfos";
+/**
+ * Fixed directory document id for tenant display metadata (`{ label }`).
+ * Encrypted under {@link PUBLIC_INFOS_KEY_ID}.
+ */
+export declare const TENANT_SETUP_DOC_ID = "tenantsetup";
 /**
  * Well-known key ID for the tenant-wide default document encryption key.
  *
  * KeyBag location: type "doc", id DEFAULT_TENANT_KEY_ID.
  */
 export declare const DEFAULT_TENANT_KEY_ID = "default";
+/**
+ * Well-known database id for the per-user encryption-identity directory
+ * (`userkey_*` documents). Protected by a builtin write invariant independent
+ * of the ACL master switch: the admin may create/delete, only the owning
+ * person may change.
+ */
+export declare const USER_DIRECTORY_DB_ID = "userdirectory";
+/**
+ * Well-known database id for the tenant directory (grants, policies, key
+ * distribution). Admin-only writes; hardcoded in several call sites as
+ * `"directory"` for historical reasons.
+ */
+export declare const DIRECTORY_DB_ID = "directory";
 /**
  * JSON payload returned by `GET /.well-known/mindoodb-server-info`.
  */
@@ -154,6 +172,14 @@ export interface PreDecryptedUserKeys {
      * `EncryptedLocalCacheStore` performs internally.
      */
     cacheEncryptionKey?: CryptoKey;
+    /**
+     * PKCS8 bytes of the identity User-Key. Live-bag hosts (Haven) decrypt this
+     * once at unlock and pass it here so `createTenant` / reconcile can mint and
+     * wrap `default` to the **identity** User-Key when `currentUserPassword` is
+     * empty. Without this, a failed password decrypt used to generate a second
+     * throwaway pair and desync `acl_keydistribution_default`.
+     */
+    userKeyPrivateBytes?: Uint8Array;
 }
 interface CreateTenantPasswords {
     /** Password for the admin user's private keys */
@@ -162,10 +188,10 @@ interface CreateTenantPasswords {
      * Password for the regular (app) user's private keys.
      *
      * When {@link existingKeyBag} **and** {@link preDecryptedAppUserKeys}
-     * are both supplied the password is no longer needed by `createTenant`
-     * (the bag has already been wrapped, and `openTenant` consumes the
-     * pre-imported `CryptoKey`s directly). Callers in that live-bag mode
-     * may pass an empty string.
+     * are both supplied, signing/encryption private keys skip password
+     * decrypt. The identity User-Key still needs either `userPassword` or
+     * {@link PreDecryptedUserKeys.userKeyPrivateBytes} — otherwise mint
+     * cannot wrap `default` to the existing pair.
      */
     userPassword: string;
     /**
@@ -200,6 +226,12 @@ interface CreateTenantPasswords {
      * (legacy behavior: v1 entries remain acceptable).
      */
     requireV2Entries?: boolean;
+    /**
+     * Optional human-readable tenant label stored in the directory document
+     * `tenantsetup` (doc under `$publicinfos`; label field-encrypted under
+     * `default`). When omitted, no setup document is written at create time.
+     */
+    tenantLabel?: string;
 }
 /**
  * Options for creating a new tenant with a single convenience call.
@@ -250,6 +282,12 @@ export interface JoinRequest {
      * Emitting `2` only for nameless requests keeps older readers from silently
      * registering an undefined username — they reject the unknown version
      * instead.
+     *
+     * The `mdb://join-request/...` transport has a third version that is not
+     * visible here: `v: 3` is the compact, PEM-stripped payload written by
+     * `encodeJoinRequestUri`. It carries the same information, and
+     * `decodeJoinRequestUri` normalizes it back to `1` or `2` depending on
+     * whether a username is present.
      */
     v: 1 | 2;
     /**
@@ -268,13 +306,20 @@ export interface JoinRequest {
     /** RSA-OAEP public encryption key (PEM format) */
     encryptionPublicKey: string;
     /**
-     * Optional human-readable label for this device's signing/encryption key
+     * Human-readable label for this device's signing/encryption key
      * pair (e.g. a date or a note about the device type). Suggested by the
      * joining user; the approving admin may override it (see
-     * {@link ApproveJoinRequestOptions.label}). Stored on the grant document's
-     * key-pair entry and editable later (docs/accesscontrol.md §6.5).
+     * {@link ApproveJoinRequestOptions.label}). Required when granting access.
+     * Stored on the grant document's key-pair entry and editable later
+     * (docs/accesscontrol.md §6.5).
      */
     label?: string;
+    /**
+     * Public half of the joining device's person-bound User-Key (RSA-OAEP 3072
+     * PEM). The admin publishes it as a pending `userkey_*` document on approval
+     * and wraps `default` to it. Required for a new person's first device.
+     */
+    userPublicKey?: string;
 }
 /**
  * Options for approving a join request.
@@ -284,8 +329,12 @@ export interface ApproveJoinRequestOptions {
     adminSigningKey: EncryptedPrivateKey;
     /** The password to decrypt the admin signing key */
     adminPassword: string;
-    /** A shared password for encrypting the exported keys. Must be communicated out-of-band (e.g. phone). */
-    sharePassword: string;
+    /**
+     * @deprecated Join responses are RSA-OAEP-wrapped to the requester's
+     * `encryptionPublicKey` (v3). Ignored when present; kept so older callers
+     * that still pass a share password continue to type-check.
+     */
+    sharePassword?: string;
     /** Optional server URL to include in the response so the joining user knows where to sync */
     serverUrl?: string;
     /** Optional admin username to include in the response so the joining user can display it */
@@ -299,10 +348,11 @@ export interface ApproveJoinRequestOptions {
      */
     sharedDocKeyIds?: string[];
     /**
-     * Optional human-readable label for the joining device's key pair. When set,
+     * Human-readable label for the joining device's key pair. When set,
      * it overrides any label the joining user suggested in the join request and
      * is stored on the grant document's key-pair entry (docs/accesscontrol.md
-     * §6.5). Useful for recording a date or a note about the device type.
+     * §6.5). Required: the join request or this field must supply a non-empty
+     * label.
      */
     label?: string;
     /**
@@ -315,14 +365,28 @@ export interface ApproveJoinRequestOptions {
      * than trusting the requester's spelling (§6.5).
      */
     username?: string;
+    /**
+     * Optional tenant display label to include in the join response. When omitted,
+     * `approveJoinRequest` tries to decrypt it from the directory `tenantsetup`
+     * doc (`label_encrypted` under the tenant `default` key).
+     */
+    tenantLabel?: string;
     /** If "uri", approveJoinRequest returns a mdb://join-response/... URI string instead of an object */
     format?: "object" | "uri";
 }
 export interface JoinResponseEncryptedDocKeyVersion {
     /** Original KeyBag creation timestamp for this key version, used for rotation ordering. */
     createdAt?: number;
-    /** Symmetric document key version encrypted with the shared password. */
-    encryptedKey: EncryptedPrivateKey;
+    /**
+     * v2: symmetric document key version encrypted with the sharePassword.
+     * Absent on v3 responses.
+     */
+    encryptedKey?: EncryptedPrivateKey;
+    /**
+     * v3: raw AES key RSA-OAEP-wrapped to the join requester's
+     * `encryptionPublicKey` (standard base64). Absent on v2 responses.
+     */
+    wrappedKey?: string;
 }
 export interface JoinResponseEncryptedDocKey {
     /** Logical document key id within the tenant, e.g. "$publicinfos", "default", or a named key. */
@@ -335,11 +399,14 @@ export interface JoinResponseEncryptedDocKey {
  * It contains encrypted symmetric keys and tenant metadata needed to join.
  *
  * Can be serialized to a mdb://join-response/... URI for out-of-band exchange.
- * The encrypted keys can only be unlocked with the sharePassword communicated separately.
+ *
+ * v3 wraps each document key to the join requester's RSA encryption public
+ * key, so only that device can unwrap the payload — no share password.
+ * v2 responses (sharePassword) remain readable for backward compatibility.
  */
 export interface JoinResponse {
-    /** Protocol version. v2 carries versioned document-key bundles. */
-    v: 2;
+    /** Protocol version. v2 is password-wrapped; v3 is RSA-OAEP-wrapped to the requester. */
+    v: 2 | 3;
     /** Tenant identifier */
     tenantId: string;
     /** Admin's public signing key (Ed25519, PEM) — needed to open the tenant */
@@ -350,6 +417,13 @@ export interface JoinResponse {
     serverUrl?: string;
     /** Optional admin username for display purposes */
     adminUsername?: string;
+    /**
+     * Optional human-readable tenant label for display on the joining device.
+     * Snapshotted at approve time from `tenantsetup` (or an explicit override).
+     * After join, clients should prefer the live directory label (field-encrypted
+     * under `default`) when synced.
+     */
+    tenantLabel?: string;
     /**
      * The username the joining device was actually registered as.
      *
@@ -359,7 +433,7 @@ export interface JoinResponse {
      * requester keeps the name it chose itself.
      */
     username?: string;
-    /** Selected tenant document keys, encrypted with the sharePassword. */
+    /** Selected tenant document keys. v3: RSA-wrapped; v2: sharePassword-encrypted. */
     encryptedDocKeys: JoinResponseEncryptedDocKey[];
 }
 /**
@@ -380,8 +454,11 @@ export interface JoinTenantOptions {
      * callers may pass an empty string.
      */
     password: string;
-    /** The shared password used to decrypt the keys in the join response */
-    sharePassword: string;
+    /**
+     * The shared password used to decrypt v2 join responses.
+     * Unused for v3 (RSA-wrapped) responses; callers may omit it.
+     */
+    sharePassword?: string;
     /**
      * Optional pre-existing {@link KeyBag} to extend with the joined tenant's
      * keys. When supplied, `joinTenant` will mutate this bag in place (adding
@@ -424,6 +501,58 @@ export interface JoinTenantResult {
      */
     user: PrivateUserId;
 }
+/**
+ * One tenant delivered by `POST /device/discover` after device-key proof.
+ * No cleartext label or username — those arrive RSA-hybrid-wrapped to this
+ * device (`wrappedJoinResponse`) and/or later via `tenantsetup` under `default`.
+ */
+export interface DeviceTenantDelivery {
+    tenantId: string;
+    adminSigningPublicKey: string;
+    adminEncryptionPublicKey: string;
+    /** AES `$publicinfos` RSA-OAEP-wrapped to this device's encryption public key (base64). */
+    wrappedPublicInfosKey: string;
+    /** All `$publicinfos` versions, oldest first. `wrappedPublicInfosKey` is the newest. */
+    wrappedPublicInfosKeys?: string[];
+    /**
+     * Per-device join bootstrap from the grant (`userKeyPairs[].joinResponseWrapped`):
+     * username + optional tenantLabel/adminUsername, RSA-hybrid-encrypted to this
+     * device. Opaque to the server; the joining device unwraps it locally.
+     */
+    wrappedJoinResponse?: string;
+    username_hash?: string;
+    identity_hashes?: string[];
+}
+export interface DiscoverTenantsOnServerOptions {
+    user: PrivateUserId;
+    password: string;
+    /** When set, skip password-decrypt of the signing key. */
+    preDecryptedUserKeys?: PreDecryptedUserKeys;
+}
+export interface BootstrapTenantFromDeliveryOptions {
+    user: PrivateUserId;
+    password: string;
+    existingKeyBag?: KeyBag;
+    preDecryptedUserKeys?: PreDecryptedUserKeys;
+    /**
+     * When set, pull the directory from this server URL after open and run
+     * key-distribution reconcile (imports `default`, may adopt username).
+     */
+    serverUrl?: string;
+}
+export interface BootstrapTenantFromDeliveryResult {
+    tenant: MindooTenant;
+    keyBag: KeyBag;
+    user: PrivateUserId;
+    /** Display label after `default` import + `tenantsetup` decrypt, if available. */
+    tenantLabel?: string;
+    /**
+     * Display name of the approving admin, snapshotted into the per-device join
+     * bootstrap at approve time. Absent for grants written before this field or
+     * when the admin approved without passing a name.
+     */
+    adminUsername?: string;
+}
 /**
  * Options for publishing a tenant to a server.
  */
@@ -534,18 +663,39 @@ export interface MindooTenantFactory {
         format?: "object" | "uri";
         label?: string;
     }): JoinRequest | string;
+    /**
+     * Generate a person-bound User-Key on `user` if it does not already have one.
+     * The private half is password-encrypted with salt `"userkey"` and stored on
+     * the identity so paper backup includes it.
+     */
+    ensureUserKeyPair?(user: PrivateUserId, password: string): Promise<EncryptionKeyPair>;
     /**
      * Join a tenant using a join response from an admin.
      * This orchestrates:
      * 1. Parsing the join response (object or mdb:// URI string)
-     * 2. Creating a new KeyBag and importing the encrypted keys
+     * 2. Creating a new KeyBag and importing the encrypted keys (RSA unwrap for
+     *    v3, sharePassword for legacy v2)
      * 3. Opening the tenant with the admin public keys from the response
      *
      * @param joinResponse A JoinResponse object or a mdb://join-response/... URI string
-     * @param options Options including the user's identity, password, and the shared password
+     * @param options Options including the user's identity and password
      * @return The opened tenant and KeyBag
      */
     joinTenant(joinResponse: JoinResponse | string, options: JoinTenantOptions): Promise<JoinTenantResult>;
+    /**
+     * Prove possession of the device signing key against a MindooDB server and
+     * receive every local tenant where that key has an active grant, each with
+     * RSA-wrapped `$publicinfos`, admin public keys, and the per-device join
+     * bootstrap (username / tenant label) when the grant carries it.
+     */
+    discoverTenantsOnServer?(serverUrl: string, options: DiscoverTenantsOnServerOptions): Promise<DeviceTenantDelivery[]>;
+    /**
+     * Bootstrap a local tenant from a {@link DeviceTenantDelivery}: unwrap
+     * `$publicinfos`, adopt username from `wrappedJoinResponse` when present,
+     * open the tenant, optionally pull the directory and reconcile key
+     * distributions (`default`).
+     */
+    bootstrapTenantFromDelivery?(delivery: DeviceTenantDelivery, options: BootstrapTenantFromDeliveryOptions): Promise<BootstrapTenantFromDeliveryResult>;
 }
 /**
  * A MindooTenant contains multiple MindooDB in an organization. One MindooDB is a mandatory part
@@ -564,7 +714,7 @@ export interface MindooTenant {
      */
     getFactory(): MindooTenantFactory;
     /**
-     * Get the ID of the tenant (UUID7 format)
+     * Get the ID of the tenant (lowercase MongoDB-style ObjectId when auto-generated)
      *
      * @return The ID of the tenant
      */
@@ -629,10 +779,16 @@ export interface MindooTenant {
      * This is used for operations that need to sign with a different key than the current user's,
      * such as directory operations that must be signed with the administration key.
      *
+     * After signing, the signature is verified against `signingKeyPair.publicKey`.
+     * A mismatch (claimed admin PEM + unrelated private key) throws — this is what
+     * keeps admin-only directory writes from succeeding locally when the wrong
+     * identity is supplied.
+     *
      * @param payload The payload to sign (binary data)
      * @param signingKeyPair The signing key pair to use (Ed25519)
      * @param password The password to decrypt the signing private key
      * @return The signature (Ed25519 signature as Uint8Array)
+     * @throws when the decrypted private key does not correspond to `publicKey`
      */
     signPayloadWithKey(payload: Uint8Array, signingKeyPair: SigningKeyPair, password: string): Promise<Uint8Array>;
     /**
@@ -759,6 +915,7 @@ export interface MindooTenant {
     reconcileKeyDistributionsForCurrentUser?(): Promise<{
         imported: string[];
         removed: string[];
+        adoptedUsername?: string;
     }>;
     /**
      * Return whether the current KeyBag can resolve the given document
@@ -767,6 +924,13 @@ export interface MindooTenant {
      * result as a guard before attempting decryption.
      */
     hasDecryptionKey?(decryptionKeyId: string): Promise<boolean>;
+    rememberSealedGenerations?(keyId: string, generations: Uint8Array[]): void;
+    getSealedGenerations?(keyId: string): Uint8Array[];
+    ingestSealedRecipients?(keyId: string, recipients: import("./userkeys/sealedTypes").EntryRecipients): Promise<void>;
+    ingestSealedFromEntries?(keyId: string, entries: Array<{
+        recipients?: import("./userkeys/sealedTypes").EntryRecipients;
+        createdAt: number;
+    }>): Promise<void>;
     /**
      * Return a stable, opaque fingerprint of the doc keys this tenant
      * currently has access to. The fingerprint must change whenever the
@@ -796,17 +960,36 @@ export interface MindooTenant {
      * This orchestrates:
      * 1. Parsing the join request (object or mdb:// URI string)
      * 2. Registering the user in the tenant directory
-     * 3. Exporting selected document keys, encrypted with the sharePassword
-     * 4. Packaging everything into a JoinResponse
+     * 3. Exporting selected document keys, RSA-OAEP-wrapped to the requester
+     * 4. Packaging everything into a JoinResponse (v3)
      *
      * @param joinRequest A JoinRequest object or a mdb://join-request/... URI string
-     * @param options Options including admin key, share password, and optional server URL
+     * @param options Options including admin key and optional server URL
      * @return A JoinResponse object, or a mdb://join-response/... URI string if format is "uri"
      */
     approveJoinRequest(joinRequest: JoinRequest | string, options: ApproveJoinRequestOptions & {
         format: "uri";
     }): Promise<string>;
     approveJoinRequest(joinRequest: JoinRequest | string, options: ApproveJoinRequestOptions): Promise<JoinResponse>;
+    /** Devices on this person's grant that still need a User-Key wrap. */
+    listPendingUserKeyDevices?(): Promise<import("./userkeys/types").PendingUserKeyDevice[]>;
+    listUserKeyDevices?(): Promise<import("./userkeys/types").UserKeyDeviceRow[]>;
+    approveUserKeyDevice?(fingerprint: string): Promise<void>;
+    declineUserKeyDevice?(fingerprint: string): Promise<void>;
+    undoDeclineUserKeyDevice?(fingerprint: string): Promise<void>;
+    rotateUserKey?(): Promise<void>;
+    reconcileUserKeys?(options?: {
+        allowSelfCreate?: boolean;
+    }): Promise<import("./userkeys/types").UserKeyEnrollmentStatus>;
+    getUserKeyEnrollmentStatus?(): Promise<import("./userkeys/types").UserKeyEnrollmentStatus>;
+    noteUserDirectoryFetched?(): void;
+    noteUserDirectoryFetchFailed?(error: unknown): void;
+    ensureLocalUserKeyPair?(): Promise<void>;
+    getUserKeyManager(): import("./userkeys/UserKeyManager").UserKeyManager;
+    isDatabaseOpen?(dbId: string): boolean;
+    isDatabaseReady?(dbId: string): boolean;
+    scheduleUserKeyReconcile?(): void;
+    reconcileUserKeysSafe?(): Promise<void>;
     /**
      * Publish (register) this tenant on a MindooDB server.
      * Sends an HTTP POST to the server's /admin/register-tenant endpoint
@@ -868,7 +1051,7 @@ export interface StoreEntryMetadata {
     /**
      * Unique identifier for this entry (primary key in the store).
      * - For doc_* entries: "<docId>_d_<depsFingerprint>_<automergeHash>"
-     * - For attachment_chunk: "<docId>_a_<fileUuid7>_<base62ChunkUuid7>"
+     * - For attachment_chunk: "<docId>_a_<fileUuid7>_<chunkObjectId>"
      *
      * The structured ID format enables:
      * - Guaranteed uniqueness across documents
@@ -1001,6 +1184,18 @@ export interface StoreEntryMetadata {
      * on-disk, IndexedDB and network serializers without per-field binary handling.
      */
     provenance?: EntryProvenance;
+    /**
+     * Sealed-document recipient block (docs/userkeys.md §9.7). Present only on
+     * entries that change the recipient set. Bound into `metadataSignature` as
+     * tagged trailing block `0x03`.
+     *
+     * Plain JSON (wraps carry base64 ciphertext) so it survives the on-disk,
+     * IndexedDB and network serializers without per-field binary handling. The
+     * HTTP codec MUST include this field: dropping it on the wire makes the
+     * server rebuild signing bytes without the recipients block and reject the
+     * entry as an invalid author signature.
+     */
+    recipients?: import("./userkeys/sealedTypes").EntryRecipients;
     /**
      * Original size of the plaintext data before encryption (in bytes).
      * For doc_* entries: size of the Automerge binary change/snapshot
@@ -1386,17 +1581,17 @@ export interface SnapshotConfig {
 /**
  * Regex used to validate caller-provided MindooDoc IDs.
  *
- * The first character must be an ASCII letter; subsequent characters may be
- * ASCII letters, ASCII digits, or `_`. This keeps caller-provided IDs safe to
- * use unmodified in content-addressed store entry IDs and on disk.
+ * The first character must be an ASCII lowercase letter; subsequent characters
+ * may be ASCII lowercase letters, ASCII digits, or `_`. Lowercase-only keeps
+ * caller-provided IDs safe on case-insensitive filesystems (Windows / APFS).
  */
 export declare const CUSTOM_DOC_ID_REGEX: RegExp;
 /**
  * Regex used to validate `CreateOptions.idPrefix`.
  *
- * A prefix is a short (1–10 chars) ASCII-alphanumeric tag starting with a
- * letter, e.g. `"cls"`. It must NOT contain `_` — MindooDB appends the `_`
- * separator itself when building the final id `<prefix>_<22-char-base62>`.
+ * A prefix is a short (1–10 chars) ASCII-alphanumeric lowercase tag starting
+ * with a letter, e.g. `"cls"`. It must NOT contain `_` — MindooDB appends the
+ * `_` separator itself when building the final id `<prefix>_<24-char-objectid>`.
  */
 export declare const DOC_ID_PREFIX_REGEX: RegExp;
 /**
@@ -1405,7 +1600,7 @@ export declare const DOC_ID_PREFIX_REGEX: RegExp;
 export interface CreateOptions {
     /**
      * Caller-provided document ID. When provided it must match
-     * `^[A-Za-z][A-Za-z0-9_]*$` (see `CUSTOM_DOC_ID_REGEX`). When omitted, a fresh
+     * `^[a-z][a-z0-9_]*$` (see `CUSTOM_DOC_ID_REGEX`). When omitted, a fresh
      * time-sortable ID is generated (see `idPrefix` for the format).
      *
      * If a document with this ID already exists locally, `createDocument()`
@@ -1435,10 +1630,10 @@ export interface CreateOptions {
      */
     assumeUniqueId?: boolean;
     /**
-     * Optional short prefix (1–10 ASCII-alphanumeric chars, starting with a
-     * letter; see `DOC_ID_PREFIX_REGEX`) for a MindooDB-generated document ID.
-     * The final ID is `<idPrefix>_<22-char-base62(uuidv7)>`, e.g.
-     * `cls_0BqXa9yTFn2M4kVzR1sWpq` — time-sortable within the same prefix.
+     * Optional short lowercase prefix (1–10 ASCII-alphanumeric chars, starting
+     * with a letter; see `DOC_ID_PREFIX_REGEX`) for a MindooDB-generated document
+     * ID. The final ID is `<idPrefix>_<24-char-objectid>`, e.g.
+     * `cls_507f1f77bcf86cd799439011` — time-sortable within the same prefix.
      *
      * Unlike a custom `id`, uniqueness is guaranteed by MindooDB itself, so the
      * create follows the generated-ID code path: a single `doc_create` entry
@@ -1453,6 +1648,17 @@ export interface CreateOptions {
      * (the tenant key). Replaces `createEncryptedDocument(decryptionKeyId)`.
      */
     decryptionKeyId?: string;
+    /**
+     * Readers of this document. Mutually exclusive with `decryptionKeyId`.
+     * A fresh document key is generated and sealed to each recipient. User
+     * names are canonicalized (`CN=alice/O=contoso`, case-insensitive) and
+     * must include `O=` — the tenant id is not substituted for the organization.
+     * Directory groups are not a recipient target: list the people who should
+     * read the document so `_encryptFor` stays an explicit, queryable set.
+     * The author is included unless `recipientOptions.includeSelf` is false.
+     */
+    recipients?: import("./userkeys/sealedTypes").RecipientSpec[];
+    recipientOptions?: import("./userkeys/sealedTypes").RecipientOptions;
     /**
      * Optional signing key pair to sign the initial document entry with. When
      * provided, `signingKeyPassword` must be provided as well. Replaces
@@ -1547,7 +1753,7 @@ export interface ListDocumentIdsOptions {
     /**
      * Restrict the result to documents whose id matches this prefix. Matching is
      * boundary-aware: an id matches when it equals `idPrefix` exactly or begins
-     * with `<idPrefix>_`, mirroring the `<prefix>_<base62>` id scheme produced by
+     * with `<idPrefix>_`, mirroring the `<prefix>_<objectId>` id scheme produced by
      * `createDocument({ idPrefix })`. So `"cls"` matches `cls_…` documents but not
      * an unrelated `classroom_…` id. Omit (or pass an empty string) for no filter.
      */
@@ -1685,6 +1891,16 @@ export interface MindooDoc {
      *   inaccessible-key tombstone.
      */
     isAccessible(): boolean;
+    isSealed(): boolean;
+    getRecipients(): import("./userkeys/sealedTypes").ResolvedRecipient[];
+    getRecipientEpoch(): number;
+    /**
+     * True when this document uses a per-document sealed key (`$sealed:…`) and
+     * every listed user has an active `_encryptFor` entry with a DEK wrap.
+     * Usernames are matched case-insensitively after canonicalization
+     * (`CN=alice/O=contoso`) and must include `O=`.
+     */
+    isEncryptedFor(users: string | string[]): boolean;
     /**
      * Whether this document is still "awaiting witness": it has at least one
      * versioned store entry (written in the witness-aware era) that has not yet
@@ -2164,6 +2380,14 @@ export interface DirectoryUserLookup {
      * flag the grant for backfill.
      */
     identityHashesV?: number;
+    /**
+     * RSA-hybrid ciphertext of `{ username, tenantLabel?, adminUsername? }`
+     * wrapped to this device's encryption public key. `$publicinfos`-readable
+     * (the server forwards it during discovery) but not decryptable without the
+     * device private key. Absent on grants written before per-device join
+     * bootstrap.
+     */
+    joinResponseWrapped?: string;
 }
 /**
  * A single device's key pair on a grant document (docs/accesscontrol.md §6.5).
@@ -2188,6 +2412,13 @@ export interface GrantKeyPair {
     encryptionPublicKey: string;
     /** Optional human-readable label for this device/key pair. */
     label?: string;
+    /**
+     * Trusted-time (ms since Unix epoch) at which this device was added to the
+     * grant (first registration or later multi-device append). Retained when the
+     * device is revoked so admin UIs can still show when it was granted. Optional
+     * for legacy grants written before this field existed.
+     */
+    addedAt?: number;
     /**
      * When true, this device's access has been revoked but the pair is RETAINED
      * on the grant document (docs/accesscontrol.md §6.5) so admin UIs can list
@@ -2201,6 +2432,13 @@ export interface GrantKeyPair {
      * together with {@link revoked}; cleared when the device is restored.
      */
     revokedAt?: number;
+    /**
+     * RSA-hybrid ciphertext of `{ username, tenantLabel?, adminUsername? }`
+     * wrapped to this device's encryption public key. Lives on the `$publicinfos`
+     * grant envelope so discovery can deliver the registered name without
+     * `default`.
+     */
+    joinResponseWrapped?: string;
 }
 /** A {@link GrantKeyPair} enriched with its current remote-wipe status (§6.5). */
 export interface GrantKeyPairInfo extends GrantKeyPair {
@@ -2222,10 +2460,13 @@ export interface MindooTenantDirectory {
      * @param administrationPrivateKey The administration private key to sign the registration operation with (signing only)
      * @param administrationPrivateKeyPassword The password to decrypt the administration private key
      * @param userDetails The user details to register (ignored when appending a device to an existing grant)
-     * @param label Optional device label for this key pair (§6.5)
+     * @param label Device label for this key pair (§6.5). Optional for existing
+     *   test/register paths; required when granting access via {@link MindooTenant.approveJoinRequest}.
      * @return A promise that resolves when the user is registered
      */
-    registerUser(userId: PublicUserId, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string, userDetails?: DirectoryUserDetails, label?: string): Promise<void>;
+    registerUser(userId: PublicUserId, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string, userDetails?: DirectoryUserDetails, label?: string, options?: {
+        distributeKeyIds?: string[];
+    }): Promise<void>;
     /**
      * Revokes a user's access by removing their keys from the grant document
      * (docs/accesscontrol.md §6.5). Revocation is an in-place edit of the grant
@@ -2535,6 +2776,27 @@ export interface MindooTenantDirectory {
         beforeDoc: Record<string, unknown> | null;
         afterDoc: Record<string, unknown> | null;
     }): Promise<AccessDecision>;
+    /**
+     * Whether two signing keys belong to the same person (same `username_hash`
+     * grant) when resolved at the given trusted times. Used to evaluate `$author`
+     * at grant level rather than device-key equality.
+     *
+     * The creator is resolved at `creatorTrustedTime` (typically the trusted time
+     * of the `doc_create` entry) so authorship survives retirement of the
+     * creating device. The signer is resolved at `signerTrustedTime` so a
+     * revoked device cannot act as `$author`.
+     */
+    isSamePerson?(input: {
+        creatorSigningKey: string;
+        signerSigningKey: string;
+        creatorTrustedTime: number;
+        signerTrustedTime: number;
+    }): Promise<boolean>;
+    /**
+     * The `username_hash` of the grant that contained `signingKey` at trusted
+     * time `T`, or `null` when the key was not an active grant member then.
+     */
+    resolveUsernameHashForSigningKey?(signingKey: string, trustedTime: number): Promise<string | null>;
     /**
      * Whether a Tier 2 (`withfields`) content rule exists for `op` on `dbid` at
      * the current head state. Lets callers skip materializing before/after
@@ -2571,6 +2833,7 @@ export interface MindooTenantDirectory {
      * @returns The salted, normalized username hash.
      */
     getUsernameHash?(username: string): Promise<string>;
+    getUsernameHashCandidates?(username: string): Promise<string[]>;
     /**
      * All ACTIVE (non-revoked) RSA encryption public keys (PEM) for `username` —
      * one per active device. Used to wrap a key for every device of a recipient.
@@ -2590,6 +2853,13 @@ export interface MindooTenantDirectory {
      * @returns The recipient's wrapped device material.
      */
     wrapKeyForUserDevices?(keyId: string, username: string): Promise<KeyDistributionPushRecipient>;
+    wrapKeyForUser?(keyId: string, username: string, publicKeyOverride?: string): Promise<KeyDistributionPushRecipient | null>;
+    /**
+     * Merge `username` into each listed key-distribution document, wrapping to
+     * the person's published User-Key. Users without a published User-Key are
+     * skipped (pending), not wrapped to device keys.
+     */
+    autoDistributeKeysToUser?(username: string, keyIds: string[], administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string, publicKeyOverride?: string): Promise<void>;
     /**
      * The version manifest (`{createdAt, fingerprint}`) of `keyId` from the
      * caller's KeyBag — the source of truth for a distribution's `keyVersions`.
@@ -2762,6 +3032,7 @@ export interface MindooTenantDirectory {
         encryptionPublicKey: string;
         details?: DirectoryUserDetails | null;
     } | null>;
+    findGrantAccessDocuments?(username: string): Promise<MindooDoc[]>;
     /**
      * Look up a user by their public signing key.
      * This is useful for reverse-resolving historical change authors to friendly labels.
@@ -2883,10 +3154,10 @@ export interface MindooTenantDirectory {
      * Returns the database IDs currently known to the directory.
      *
      * This is intended for admin tooling and overview UIs. The result always includes
-     * `"directory"` and will also include `"main"` as the conventional default app DB.
-     * Additional DBs are discovered from `dbsettings` documents stored in the directory.
+     * `"directory"`. Additional DBs are discovered from `dbsettings` documents stored
+     * in the directory.
      *
-     * @returns The database ids known to the directory (always including `"directory"` and `"main"`).
+     * @returns The database ids known to the directory (always including `"directory"`).
      */
     listKnownDBIds(): Promise<string[]>;
     /**
@@ -4139,6 +4410,25 @@ export interface MindooDB {
      * @param signingKeyPair Optional custom signing key (matches `changeDoc`).
      */
     canChange(doc: MindooDoc, candidateAfter: Record<string, unknown>, signingKeyPair?: SigningKeyPair): Promise<AccessDecision>;
+    /**
+     * Add readers to a sealed document. Cheap: one RSA wrap per new user, no
+     * rotation. The new readers can decrypt the whole history. Names are
+     * canonicalized (`CN=alice/O=contoso`) and matched case-insensitively;
+     * they must include `O=`.
+     */
+    addRecipients(doc: MindooDoc, recipients: import("./userkeys/sealedTypes").RecipientSpec[], options?: import("./userkeys/sealedTypes").RecipientChangeOptions): Promise<import("./userkeys/sealedTypes").RecipientChangeResult>;
+    /**
+     * Drop readers from a sealed document. Rotates the document key: removed
+     * readers keep what they already have, and cannot read later changes.
+     * Names are canonicalized and matched case-insensitively.
+     */
+    removeRecipients(doc: MindooDoc, recipients: import("./userkeys/sealedTypes").RecipientSpec[], options?: import("./userkeys/sealedTypes").RecipientChangeOptions): Promise<import("./userkeys/sealedTypes").RecipientChangeResult>;
+    /**
+     * Replace the recipient list. Diffs against the current set: additions wrap,
+     * removals rotate. The author stays on the list unless `includeSelf: false`.
+     */
+    setRecipients(doc: MindooDoc, recipients: import("./userkeys/sealedTypes").RecipientSpec[], options?: import("./userkeys/sealedTypes").RecipientChangeOptions): Promise<import("./userkeys/sealedTypes").RecipientChangeResult>;
+    canChangeRecipients(doc: MindooDoc, next: import("./userkeys/sealedTypes").RecipientSpec[]): Promise<AccessDecision>;
     /**
      * Predict whether deleting `doc` via `deleteDocument` would be allowed by the
      * active write policy, without writing.