mindoodb 0.0.23 → 0.0.32

package/dist/core/BaseMindooTenantDirectory.d.ts

@@ -1,30 +1,636 @@
-import { type DirectoryUserDetails, type DirectoryUserLookup, EncryptedPrivateKey, MindooDB, MindooDoc, MindooTenantDirectory, PublicUserId } from "./types";
+import { type DirectoryUserDetails, type DirectoryUserLookup, type GrantKeyPair, type GrantKeyPairInfo, EncryptedPrivateKey, MindooDB, MindooDoc, MindooTenantDirectory, PublicUserId } from "./types";
 import { BaseMindooTenant } from "./BaseMindooTenant";
 import { Logger } from "./logging";
-export declare class BaseMindooTenantDirectory implements MindooTenantDirectory {
+import { KeyBagReconciler } from "./accesscontrol/keyBagReconciler";
+import { DirectoryStateNode } from "./accesscontrol/DirectoryStateNode";
+import { AclRuleDoc, DefaultAccessPolicyDoc, KeyDistributionPushRecipient, KeyDistributionRequest, KeyDistributionView, KeyVersionRef, RuleTargets, RuleType, WithFieldClause, AppDistributionRequest, AppDistributionView, AppDistributionReconcilePlan, SyncSetupPolicyRequest, SyncSetupPolicyView, SyncSetupPolicyReconcilePlan, DocHistoryPurgeRequest, DocHistoryPurgeView } from "./accesscontrol/types";
+import { IdentitySet } from "./accesscontrol/evaluate";
+import { AccessDecision } from "./accesscontrol/types";
+export declare class BaseMindooTenantDirectory implements MindooTenantDirectory, KeyBagReconciler {
     private tenant;
     private directoryDB;
     private trustedKeysCache;
-    private grantDocIdToPublicKey;
+    private grantDocIdToSigningKeys;
     private userLookupCache;
+    private wipeKeyToGrantDocId;
     private tenantSettingsCache;
     private dbSettingsCache;
     private groupsCache;
+    private keyDistributionCache;
+    private appDistributionCache;
+    private syncSetupPolicyCache;
+    private timeTravel;
+    private lastTimeTravelChangeSeq;
     private unifiedCacheLastCursor;
     private lastDirectorySyncTimestamp;
+    private metadataSignatureCutoffCache;
+    private metadataSignatureCutoffCachedAt;
+    private resolvingMetadataSignatureCutoff;
     private logger;
     constructor(tenant: BaseMindooTenant, logger?: Logger);
     getDirectoryDB(): Promise<MindooDB>;
-    registerUser(userId: PublicUserId, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string, userDetails?: DirectoryUserDetails): Promise<void>;
+    registerUser(userId: PublicUserId, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string, userDetails?: DirectoryUserDetails, label?: string): Promise<void>;
     findGrantAccessDocuments(username: string): Promise<MindooDoc[]>;
-    revokeUser(username: string, requestDataWipe: boolean, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
-    validatePublicSigningKey(publicKey: string): Promise<boolean>;
+    /**
+     * Revoke a user's access by removing their keys from the grant document
+     * (docs/accesscontrol.md §6.5). This replaces the legacy `revokeaccess`
+     * document model entirely: revocation is now an in-place edit of the grant
+     * document's `userSigningPublicKeys` / `userEncryptionPublicKeys` arrays.
+     *
+     * By default (no `options.signingKeys`) the user is fully revoked: every
+     * signing AND encryption key is removed, so the grant document remains but
+     * carries no keys. To revoke a single device/key, pass the specific
+     * `signingKeys` (and optionally matching `encryptionKeys`) to remove.
+     *
+     * When `options.requestDataWipe` is true, the removed signing keys are also
+     * flagged for a remote device wipe (§6.5) before removal, so the targeted
+     * devices delete their local tenant on next sync. The wipe directive is
+     * stored self-contained on the grant document and survives key removal.
+     *
+     * BREAKING CHANGE: the previous signature took a positional `requestDataWipe`
+     * boolean; it now takes an options object so specific keys can be targeted.
+     *
+     * @param username The user to revoke (format: "CN=<username>/O=<tenantId>").
+     * @param options.signingKeys Specific signing keys to remove; omit/empty to
+     *   remove all of the user's keys (full revocation).
+     * @param options.encryptionKeys Specific encryption keys to remove. Ignored
+     *   for a full revocation (all encryption keys are removed in that case).
+     * @param options.requestDataWipe Also request a remote wipe of the removed
+     *   signing keys' devices.
+     */
+    revokeUser(username: string, options: {
+        signingKeys?: string[];
+        encryptionKeys?: string[];
+        requestDataWipe?: boolean;
+    }, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    validatePublicSigningKey(publicKey: string, opts?: {
+        forceRefresh?: boolean;
+    }): Promise<boolean>;
     /**
      * Update all caches (trusted keys, groups, settings) by processing new changes since the last cursor.
      * This unified method processes all document types in a single loop for efficiency.
      * No signature verification is needed since the DB already enforces admin-only access.
      */
     private updateUnifiedCache;
+    /**
+     * The head time-travel directory-state node ("now"), after ensuring the chain
+     * is current. Powers access-control evaluation (§7) and audit queries.
+     */
+    getDirectoryStateHead(): Promise<DirectoryStateNode>;
+    /**
+     * The time-travel directory-state node covering trusted time `T` (§8) — used
+     * by the evaluation algorithm and `wasAllowedAt` to judge an entry against the
+     * directory as it was at the entry's trusted time.
+     */
+    getDirectoryStateAt(T: number): Promise<DirectoryStateNode>;
+    /**
+     * Lazily create the time-travel index (restoring its persisted delta log and
+     * registering it with the tenant CacheManager on first use), then bring the
+     * directory-state chain up to date from the revision-grain changefeed
+     * (docs/accesscontrol.md §8).
+     *
+     * The (potentially expensive) feed rebuild is skipped when the directory's
+     * changefeed cursor has not advanced since the previous build and no
+     * un-witnessed revisions are pending a possible trusted-time re-stamp.
+     */
+    private ensureTimeTravelCurrent;
+    /**
+     * The set of witness public keys trusted at trusted time `T`
+     * (docs/accesscontrol.md §6.4), used by the client to validate witness
+     * receipts on incoming entries during materialization (§5.4).
+     */
+    getTrustedWitnessKeysAt(T: number): Promise<Set<string>>;
+    /**
+     * Resolve the acting user's identity set for access-control evaluation
+     * (docs/accesscontrol.md §7 step 3): username hash (v1 + v2), every group hash
+     * (including nested groups), the user's resolved usernames/groups for
+     * placeholder expansion, and the applicable pseudo-tokens (`$everyone` always;
+     * `$admin`/`$author` when the caller indicates they apply).
+     *
+     * @param username The acting user's canonical username.
+     * @param opts.isAdmin Whether the acting signing key is the tenant admin key.
+     * @param opts.isAuthor Whether the acting user authored the target document
+     *   (the caller resolves this by mapping the document's creator key and the
+     *   change signer key to the same grant; see §6.3 `$author`).
+     */
+    buildIdentitySet(username: string, opts?: {
+        isAdmin?: boolean;
+        isAuthor?: boolean;
+    }): Promise<IdentitySet>;
+    /**
+     * Server-side Tier 1 evaluation for a pushed entry (docs/accesscontrol.md §7,
+     * §10). The server identifies the author by signing key (it cannot read
+     * encrypted content), resolves their identity set, and evaluates the identity
+     * tier of the policy at `trustedTime`. Tier 2 (content) rules are deferred to
+     * clients — `evaluateAccess` is called with `isServer: true`, so a gate that
+     * only a Tier 2 rule could decide is treated as allowed here.
+     *
+     * @param input.op The operation (entry type) being pushed.
+     * @param input.dbid The database the entry targets (witness binds this).
+     * @param input.signingKey The author's Ed25519 signing public key (PEM).
+     * @param input.trustedTime The trusted time to evaluate at (the witness's
+     *   acceptance time for an inbound push).
+     * @param input.isAuthor Whether the author is the document's original creator
+     *   (resolved by the caller for `$author`; see §6.3). For `doc_create` the
+     *   author is always the creator.
+     */
+    evaluateAccessForSigningKey(input: {
+        op: RuleType;
+        dbid: string;
+        signingKey: string;
+        trustedTime: number;
+        isAuthor?: boolean;
+    }): Promise<AccessDecision>;
+    /**
+     * Client-side (Tier 1 + Tier 2) evaluation for a single entry during
+     * materialization (docs/accesscontrol.md §7, §10). Unlike the server path,
+     * the client can read decrypted content, so it evaluates `withfields` clauses
+     * against the supplied `before`/`after` document states.
+     */
+    evaluateClientAccess(input: {
+        op: RuleType;
+        dbid: string;
+        signingKey: string;
+        trustedTime: number;
+        isAuthor: boolean;
+        beforeDoc: Record<string, unknown> | null;
+        afterDoc: Record<string, unknown> | null;
+    }): Promise<AccessDecision>;
+    /**
+     * Whether the active policy has any Tier 2 (`withfields`) content rule for
+     * operation `op` in database `dbid` at the current head state. Lets the
+     * client write prechecks skip the (potentially costly) Automerge -> JS
+     * materialization of the before/after document when only Tier 1
+     * (identity/op) checks could apply (docs/accesscontrol.md §9).
+     */
+    hasWriteContentRules(op: RuleType, dbid: string): Promise<boolean>;
+    /**
+     * Whether access control is active for this tenant right now: a default
+     * policy exists and the master kill-switch is not engaged
+     * (docs/accesscontrol.md §6.1, §7 step 0). When false, callers can skip the
+     * (more expensive) per-entry access evaluation entirely.
+     */
+    isAccessControlActive(): Promise<boolean>;
+    /**
+     * The effective default `decryptionKeyId` for a `doc_create` in `dbid` at the
+     * current head state, or `undefined` when none is configured. Lets the client
+     * fill in the key when the caller omits one, instead of falling back to the
+     * hardcoded `"default"`. This is a create-time convenience, not a security
+     * control — which keys a user may create/read under is governed by key
+     * possession (the key distribution model, docs/accesscontrol.md §13).
+     */
+    getEffectiveDefaultCreateKeyId(dbid: string): Promise<string | undefined>;
+    /**
+     * The tenant-wide database-open policy at the current head state.
+     *
+     * This is a tenant-level control read only from the `acl_defaultpolicy`
+     * document (never layered per-db). When no default policy exists (access
+     * control off), or the field is omitted, the policy is `"open"`. In
+     * `"directory-restricted"` mode only `"directory"` (always implicitly
+     * allowed) and the returned `allowedDbIds` may be opened/synced.
+     */
+    getDatabaseCreationPolicy(): Promise<{
+        mode: "open" | "directory-restricted";
+        allowedDbIds: string[];
+    }>;
+    /**
+     * The tenant-wide storage-format floor (`requireMetadataSignatureSince`): the
+     * trusted-time cutoff at/after which entries must carry the v2 metadata-binding
+     * signature, or `undefined` when no floor is configured (fully backward
+     * compatible). Tenant-level only, read from the `acl_defaultpolicy` head.
+     *
+     * Cached with a short TTL and guarded against re-entrancy: resolving the
+     * cutoff loads the directory head, and directory materialization itself runs
+     * signature verification — without the guard a verify→resolve→materialize→
+     * verify cycle could recurse. During such re-entry we return the last known
+     * value (the directory store is anyway exempt from the floor by its callers).
+     */
+    getRequireMetadataSignatureSince(): Promise<number | undefined>;
+    /**
+     * Whether `dbid` may be opened/synced under the current database-open policy.
+     *
+     * Always true for `"directory"` and in `"open"` mode. In
+     * `"directory-restricted"` mode, true only when `dbid` is in `allowedDbIds`
+     * or the optional `signingKey` is the tenant administration key (admin
+     * bypass).
+     */
+    isDatabaseAllowed(dbid: string, opts?: {
+        signingKey?: string;
+    }): Promise<boolean>;
+    /**
+     * Server-oriented variant of {@link isDatabaseAllowed} that resolves the
+     * admin bypass from a request principal's signing key. Used by the sync
+     * server to gate all sync operations for a database id.
+     */
+    evaluateDbAccessForSigningKey(input: {
+        dbid: string;
+        signingKey: string;
+    }): Promise<boolean>;
+    /**
+     * Whether the current user may open and sync `dbid` under the database read
+     * gate (`doc_read`, §6.6). The client-side counterpart of
+     * {@link evaluateDbAccessForSigningKey}'s read gate: it evaluates the
+     * `doc_read` policy for the current user against the directory head. The
+     * `"directory"` database is never gated and the tenant admin is always
+     * exempt. This does NOT apply the tenant-wide database-id allowlist
+     * ({@link isDatabaseAllowed}); callers enforce both gates.
+     */
+    canReadDatabase(dbid: string): Promise<boolean>;
+    /**
+     * Create or update the tenant-wide default policy (§6.1). The mere existence
+     * of this document activates access control. Only the fields supplied are
+     * written; omit a field to leave it unset (interpreted as its default).
+     */
+    setDefaultAccessPolicy(policy: Partial<Omit<DefaultAccessPolicyDoc, "form" | "type">>, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Create or update a per-database policy override (§6.2). Fields set here
+     * override the tenant default for `dbid`; unset fields inherit it.
+     */
+    setDatabaseAccessPolicy(dbid: string, policy: Partial<Omit<DefaultAccessPolicyDoc, "form" | "type">>, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /** Shared writer for default / per-db policy documents. */
+    private writePolicyDoc;
+    /**
+     * Create or replace an access-control rule (§6.3). A rule with `withfields`
+     * is Tier 2 (client-enforced); otherwise it is Tier 1 (server-enforced). The
+     * spec is validated before writing.
+     */
+    createAccessRule(rule: {
+        ruleId: string;
+        type: RuleType;
+        dbid?: string;
+        action?: "allow" | "deny";
+        users_hashes?: string[];
+        /** Usernames to target; resolved to their (salted v2) hashes. */
+        usernames?: string[];
+        /** Group names to target; resolved to their (salted v2) hashes. */
+        groups?: string[];
+        withfields?: WithFieldClause[];
+        description?: string;
+    }, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * List access-control rules currently in effect (§9), optionally filtered by
+     * operation type and/or database. Rules with `dbid: "*"` match any database.
+     */
+    listRules(filter?: {
+        type?: RuleType;
+        dbid?: string;
+    }): Promise<Array<AclRuleDoc & {
+        targets?: RuleTargets;
+    }>>;
+    /** Delete an access-control rule by id (§9): a soft-delete of its document. */
+    deleteRule(ruleId: string, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Add (or refresh) a trusted witness (§6.4). The witness document is keyed by
+     * a fingerprint of its public key so add/remove are symmetric.
+     */
+    addTrustedWitness(witness: {
+        witnessPublicKey: string;
+        serverUrl?: string;
+    }, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /** Remove a trusted witness by its public key (§6.4): soft-deletes its document. */
+    removeTrustedWitness(witnessPublicKey: string, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Add device key pairs to a user's grant (§6.5 key rollover / new device).
+     * Pairs are merged by signing key (a pair with an already-present signing key
+     * updates its encryption key/label). See {@link mergeKeyPairs}.
+     */
+    addUserKeys(username: string, keyPairs: GrantKeyPair[], administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Revoke keys from a user's grant (§6.5 revoke a device/key). A device is
+     * identified by its signing key; revoking a signing key marks its entire
+     * paired entry revoked. `encryptionKeys` additionally targets any pair whose
+     * encryption key matches (kept for callers that target encryption keys
+     * directly).
+     *
+     * Revoked pairs are RETAINED on the grant document with `revoked: true` and a
+     * `revokedAt` timestamp (instead of being deleted), so admin UIs can list and
+     * optionally restore revoked devices. They are excluded from the active key
+     * arrays (via {@link applyKeyPairFields}), so the server/auth treat them as
+     * having no access — identical observable behavior to the previous
+     * delete-based revocation.
+     */
+    removeUserKeys(username: string, signingKeys: string[], encryptionKeys: string[], administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Set or clear the label of a device's key pair, identified by its signing
+     * public key (§6.5). An empty/whitespace `label` clears it. No-op if no pair
+     * with that signing key exists on the user's grant.
+     */
+    setKeyPairLabel(username: string, signingPublicKey: string, label: string, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Request a remote wipe of specific devices (§6.5). Targets devices by signing
+     * public key; the values are stored self-contained in
+     * `wipeRequestedForSigningKeys` so they survive key removal. This is an
+     * explicit, opt-in directive and is independent of revocation.
+     */
+    requestDeviceWipe(username: string, signingKeys: string[], administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /** Cancel a previously-requested device wipe for the given signing keys (§6.5). */
+    cancelDeviceWipe(username: string, signingKeys: string[], administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Read the current grant overview for a user, for prefilling an admin
+     * "manage user" UI: the decrypted user-details payload (requires the tenant
+     * default key, which the admin client holds), the active device key pairs,
+     * and the retained revoked device key pairs (each with its `revokedAt` and
+     * remote-wipe status). Devices are de-duplicated by signing key across the
+     * user's grant documents (most recent wins).
+     */
+    getUserGrantOverview(username: string): Promise<{
+        details: DirectoryUserDetails | null;
+        activeDevices: GrantKeyPairInfo[];
+        revokedDevices: Array<GrantKeyPair & {
+            wipeRequested: boolean;
+        }>;
+    }>;
+    /**
+     * Apply a batch of admin-signed edits to a user's grant in a single change per
+     * grant document (docs/accesscontrol.md §6.5). In one pass this:
+     *  - rewrites `user_details_encrypted` (when `changes.details` is supplied),
+     *  - recomputes the `identity_hashes` bundle + version (the per-user backfill
+     *    trigger for grants written before the bundle existed),
+     *  - sets per-device labels (`deviceLabels`: signing key → label; empty clears),
+     *  - revokes devices (`revokeSigningKeys`: marks `revoked:true` + `revokedAt`,
+     *    retaining the pair) and restores devices (`restoreSigningKeys`: clears the
+     *    revoked flags, moving the key back to active and dropping any wipe flag),
+     *  - and sets the remote-wipe set (`wipeSigningKeys`, authoritative when
+     *    supplied) minus any restored keys.
+     *
+     * This is the SDK primitive behind the Haven "Manage user" dialog's batched
+     * Save: every staged change is committed atomically per grant document.
+     */
+    updateUserGrant(username: string, changes: {
+        details?: DirectoryUserDetails;
+        deviceLabels?: Record<string, string>;
+        revokeSigningKeys?: string[];
+        restoreSigningKeys?: string[];
+        wipeSigningKeys?: string[];
+    }, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Predict whether the current user may perform `op` on `dbid` (§9). Pure read;
+     * evaluates Tier 1 + Tier 2 against the head directory state, treating the
+     * caller as the prospective author. `candidateDoc` supplies the content that
+     * `withfields` clauses are checked against.
+     */
+    canDo(op: RuleType, dbid: string, candidateDoc?: Record<string, unknown>): Promise<AccessDecision>;
+    /**
+     * Audit query (§9): would `username` have been allowed to perform `op` on
+     * `dbid` at trusted time `at`? Evaluates against the directory state as it was
+     * at `at`, so historical decisions can be explained.
+     */
+    wasAllowedAt(op: RuleType, username: string, dbid: string, at: number, candidateDoc?: Record<string, unknown>): Promise<AccessDecision>;
+    /**
+     * All ACTIVE (non-revoked) RSA encryption public keys (PEM) for `username`
+     * across the user's grant documents — one per active device. De-duplicated.
+     */
+    getUserEncryptionPublicKeys(username: string): Promise<string[]>;
+    /**
+     * Fingerprint of an RSA encryption public key (PEM): SHA-256 over the decoded
+     * SPKI body, first 8 bytes as colon-separated hex. Matches Haven's
+     * `getPublicKeyFingerprint`, so the device-map keys built here line up with
+     * what Haven UIs display. Stable for a given key value across wrap (key-holder)
+     * and reconcile (recipient) sides.
+     */
+    private encryptionKeyFingerprint;
+    /**
+     * Wrap every stored version of `keyId` (from the caller's KeyBag) to ALL
+     * active encryption devices of `username`, producing the exact `pushto`
+     * device-map shape used by both the distribution doc (`pushto_users_keys`) and
+     * the request URI (`KeyDistributionRequest.pushto[].devices`):
+     * `deviceEncKeyFingerprint -> { versionFingerprint -> wrappedKey(b64) }`.
+     * Throws if the caller does not hold the key or the recipient has no active
+     * encryption device.
+     */
+    wrapKeyForUserDevices(keyId: string, username: string): Promise<KeyDistributionPushRecipient>;
+    /**
+     * The canonical write-time hash for `username` (the value stored in
+     * `pushto_users_hashes` / `pullfrom_users_hashes`). Exposed so callers (the
+     * Haven dialog/session) can build `pullfrom` entries for users they are
+     * removing.
+     */
+    getUsernameHash(username: string): Promise<string>;
+    /**
+     * The version manifest (`{createdAt, fingerprint}`) of `keyId` from the
+     * caller's KeyBag. The single source of truth for the distribution's
+     * `keyVersions`. Empty when the key is not held.
+     */
+    getKeyVersionManifest(keyId: string): Promise<KeyVersionRef[]>;
+    /** Encrypt a UTF-8 string with the tenant default key, base64-encoded. */
+    private encryptToDefaultField;
+    /**
+     * Admin-sign and upsert the singleton `acl_keydistribution_<keyId>` document
+     * from a {@link KeyDistributionRequest} (built in-dialog or decoded from a
+     * request URI). The full desired state is written each time. Validates the
+     * structural invariants plus, against the directory, that every `pushto` user
+     * has an active grant and every active device is covered by wrapped material.
+     */
+    publishKeyDistribution(request: KeyDistributionRequest, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Decrypt a `<field>_encrypted` JSON array of strings on a distribution doc.
+     * Returns null when the field is missing/unreadable (e.g. the tenant default
+     * key is not held).
+     */
+    private decryptUsernameArray;
+    /** Parse a raw distribution doc's data into a {@link KeyDistributionView}. */
+    private toKeyDistributionView;
+    /**
+     * List all key-distribution documents at the directory head as
+     * {@link KeyDistributionView}s (decrypting display fields when the tenant
+     * default key is held; null-tolerant otherwise).
+     */
+    listKeyDistributions(): Promise<KeyDistributionView[]>;
+    /** Delete the singleton distribution document for `keyId` (admin-signed). */
+    deleteKeyDistribution(keyId: string, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Internal entry point for `MindooTenant.reconcileKeyDistributionsForCurrentUser`'s
+     * import pass ({@link KeyBagReconciler}). Unlocks this directory's OWN tenant
+     * session key and merges the key versions pushed to `username`. The key never
+     * crosses an API boundary — callers cannot supply a foreign one. Returns the
+     * imported/removed ids; both empty when the host is locked (no session key).
+     */
+    reconcileImportedKeysForCurrentUser(username: string): Promise<{
+        imported: string[];
+        removed: string[];
+    }>;
+    /**
+     * Reconcile the local KeyBag against the directory head for `username`
+     * (docs/accesscontrol.md §13), driven by an already-imported RSA-OAEP private
+     * {@link CryptoKey} (usage `["decrypt"]`). Pure function of (head, bag):
+     * idempotent and convergent, so an offline client catches up after one sync.
+     * Private: the only callers are this class's own
+     * {@link reconcileImportedKeysForCurrentUser}, which sources the key from the
+     * tenant, so no foreign key is ever applied to the bag. Per
+     * `acl_keydistribution_` doc:
+     *
+     *  - **pullfrom** (wins): remove the whole key id from the bag (all versions),
+     *    matching the server's key-id-grain blacklist; a no-op when the bag does
+     *    not hold it. The KeyBag change feed triggers visibility reconciliation,
+     *    purging the scope once the key is gone. Never touches protected ids.
+     *  - **pushto**: unwrap own device entries, VERIFY each unwrapped version's
+     *    fingerprint against the manifest (reject + log on mismatch), and merge the
+     *    missing versions (never destructive). Self-healing: a locally deleted
+     *    pushed key is re-imported here.
+     *
+     * Returns the key ids imported and removed.
+     */
+    private reconcileKeyDistributionsWithKey;
+    /**
+     * Whether `keyId` is managed by a distribution at the directory head AND the
+     * current/given user is in its `pushto` list (status is derived, never
+     * persisted in the KeyBag).
+     */
+    getManagedKeyIds(username: string): Promise<string[]>;
+    /**
+     * Admin-sign and upsert the singleton `acl_appdistribution_<appId>` document
+     * from an {@link AppDistributionRequest} (built in-dialog or decoded from a
+     * request URI). The full desired state is written each time. Validates the
+     * structural invariants plus, against the directory, that every `pushto` user
+     * has an active grant.
+     */
+    publishAppDistribution(request: AppDistributionRequest, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /** Parse a raw app-distribution doc's data into an {@link AppDistributionView}. */
+    private toAppDistributionView;
+    /**
+     * List all app-distribution documents at the directory head as
+     * {@link AppDistributionView}s (decrypting display fields when the tenant
+     * default key is held; null-tolerant otherwise).
+     */
+    listAppDistributions(): Promise<AppDistributionView[]>;
+    /** Delete the singleton distribution document for `appId` (admin-signed). */
+    deleteAppDistribution(appId: string, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Build the set of recipient-matching hashes for `username`: the user's own
+     * username-hash candidates plus the hash candidates of every group the user
+     * belongs to (resolved against the directory head). App-distribution
+     * `pushto`/`pullfrom` group hashes are written as the v3 hash of the
+     * normalized group name, which is exactly the v3 candidate of the group name,
+     * so a member intersects a group target here.
+     */
+    private appDistributionIdentityHashes;
+    /**
+     * The per-user app-distribution reconcile plan at the directory head
+     * (docs/accesscontrol.md §13): `have` is every app the user is entitled to
+     * (matched by `pushto` user/group and NOT by `pullfrom` — pull wins on any
+     * overlap), `notHave` is every other distributed app id (the user must not
+     * keep it). Drives the Haven install/update/remove pass after a directory
+     * sync. Idempotent and convergent.
+     */
+    getAppDistributionsForCurrentUser(username: string): Promise<AppDistributionReconcilePlan>;
+    /**
+     * The app ids the active/given user is entitled to receive via `pushto` at the
+     * directory head (status is derived, never persisted). Convenience wrapper
+     * over {@link getAppDistributionsForCurrentUser}.
+     */
+    getManagedAppIds(username: string): Promise<string[]>;
+    /**
+     * Admin-sign and upsert the `acl_syncsetuppolicy_<policyId>` document from a
+     * {@link SyncSetupPolicyRequest} (built in-dialog or decoded from a request
+     * URI). The full desired state is written each time. Validates the structural
+     * invariants plus, against the directory, that every `pushto` user has an
+     * active grant.
+     */
+    publishSyncSetupPolicy(request: SyncSetupPolicyRequest, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /** Parse a raw sync-setup-policy doc's data into a {@link SyncSetupPolicyView}. */
+    private toSyncSetupPolicyView;
+    /**
+     * List all sync-setup-policy documents at the directory head as
+     * {@link SyncSetupPolicyView}s (decrypting display fields when the tenant
+     * default key is held; null-tolerant otherwise).
+     */
+    listSyncSetupPolicies(): Promise<SyncSetupPolicyView[]>;
+    /** Delete the sync-setup-policy document for `policyId` (admin-signed). */
+    deleteSyncSetupPolicy(policyId: string, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * The per-user sync-setup reconcile plan at the directory head: the union of
+     * databases the user is targeted for across all policies (matched by `pushto`
+     * user/group), each carrying the effective lock state. A database is locked
+     * when a `permanent` policy targets it AND the user is not released via
+     * `pullfrom`; lock wins on overlap. A user only present in `pullfrom` (never
+     * in `pushto`) is not targeted. Drives the Haven Sync-page seed/lock pass
+     * after a directory sync. Idempotent and convergent.
+     */
+    getSyncSetupForCurrentUser(username: string): Promise<SyncSetupPolicyReconcilePlan>;
+    /**
+     * The decryption key ids revoked for `username` at the directory head: every
+     * `acl_keydistribution_<keyId>` whose `pullfrom_users_hashes` matches one of
+     * the user's hash candidates (docs/accesscontrol.md §13). Protected ids (the
+     * tenant default / public-infos keys) are never reported. Read straight from
+     * the {@link keyDistributionCache} (O(cache size), no doc scan) so the sync
+     * server can apply the per-user blacklist on every pull/push, and the client
+     * can bulk-remove these ids from its KeyBag.
+     */
+    getRevokedDecryptionKeyIdsForUser(username: string): Promise<string[]>;
+    /**
+     * Signing-key variant of {@link getRevokedDecryptionKeyIdsForUser}, for the
+     * sync server which authenticates principals by signing public key. The tenant
+     * admin and any non-user (service) key are never revoked, so they get an empty
+     * list.
+     *
+     * Matching is done purely in hash space against the grant's precomputed,
+     * `$publicinfos`-readable `identity_hashes` bundle (docs/accesscontrol.md §6.5,
+     * §13). This is the ONLY form that works on a real sync server: the server
+     * holds only the `$publicinfos` key, never the tenant default key, so it can
+     * NEVER decrypt `user_details_encrypted` — {@link getUserBySigningPublicKey}
+     * returns the bare `username_hash` as `username`. Re-hashing that single hash
+     * (routing through {@link getRevokedDecryptionKeyIdsForUser}, the old behavior)
+     * produces hash-of-hash values that cannot match the multi-variant
+     * `pullfrom_users_hashes`, so the blacklist silently did nothing on the server.
+     * The precomputed bundle, written from the cleartext name at grant time, is
+     * server-readable and carries every variant.
+     */
+    getRevokedDecryptionKeyIdsForSigningKey(signingKey: string): Promise<string[]>;
+    /**
+     * The hash set identifying a looked-up grant, for hash-space matching against
+     * directory rules / blacklists (docs/accesscontrol.md §6.5). Prefers the
+     * precomputed `$publicinfos`-readable `identity_hashes` bundle (the v1/v2/v3
+     * hashes of every DN-hierarchy username variant), so it works on a sync server
+     * that cannot read the cleartext name. Legacy grants written before the bundle
+     * existed (`identityHashesV` 0/absent) carry only the single exact-match
+     * `username_hash`; when the cleartext name IS available (a client that holds
+     * the tenant key) we additionally recompute the scheme variants so matching is
+     * no weaker than before the bundle existed.
+     */
+    private identityHashesForLookup;
+    /**
+     * Hash-space core of the revoked-key blacklist (docs/accesscontrol.md §13):
+     * every `acl_keydistribution_<keyId>` whose `pullfrom_users_hashes` intersects
+     * `myHashes`. Protected ids (the tenant default / public-infos keys) are never
+     * reported. Reads straight from {@link keyDistributionCache} (O(cache size),
+     * no doc scan); the caller must have refreshed it first (both entry points do,
+     * via `updateUnifiedCache` / `getUserBySigningPublicKey`).
+     */
+    private collectRevokedKeyIdsForHashes;
+    /** Encode bytes as base64 (mirrors RSAEncryption's transport encoding). */
+    private bytesToBase64;
+    /** Decode a base64 string into bytes. */
+    private base64ToBytes;
+    /**
+     * Load the user's active grant document and apply an admin-signed edit to its
+     * key/wipe arrays. Shared by {@link addUserKeys}, {@link removeUserKeys},
+     * {@link requestDeviceWipe}, and {@link cancelDeviceWipe}.
+     */
+    private editGrantArrays;
+    /** Load an ACL document by its fixed id, creating it (admin-signed) if absent. */
+    private getOrCreateAclDoc;
+    /**
+     * Resolve the identity set for a signing key (admin, granted user, or trusted
+     * non-user key), shared by the server and client evaluation paths.
+     */
+    private identitySetForSigningKey;
+    /**
+     * The identity set for a key with no resolvable username (admin or a trusted
+     * service key): only the pseudo-tokens apply.
+     */
+    private minimalIdentitySet;
+    /**
+     * Build an identity set for access evaluation purely from a set of identity
+     * hashes (docs/accesscontrol.md §6.5/§7), without the cleartext username. Used
+     * on a $publicinfos-only sync server, which cannot read the cleartext name but
+     * must still match Tier 1 username/group rules in hash space. Group membership
+     * is resolved from the hashes (group docs store `members_hashes` and a
+     * `$publicinfos`-readable `groupName`), and each resolved group's name hashes
+     * are folded in so group-targeted rules match. Cleartext
+     * `username`/`usernames`/`groups` are left empty: the server defers every
+     * Tier 2 (placeholder) rule to clients, so they are never read here.
+     */
+    private buildIdentitySetFromHashes;
     /**
      * Normalize group name to lowercase for case-insensitive comparison.
      */
@@ -42,6 +648,15 @@ export declare class BaseMindooTenantDirectory implements MindooTenantDirectory
      * Stops on cycles with a console warning.
      */
     private resolveGroupsForUser;
+    /**
+     * Hash-space core of {@link resolveGroupsForUser}: given the set of a user's
+     * username-variant hashes (v1+v2 of every DN-hierarchy variant), recursively
+     * resolve all groups that contain the user (directly or via nested groups).
+     * Works purely from hashes, so the server can resolve group membership for a
+     * key-based reader using the precomputed `identity_hashes` bundle — no
+     * cleartext username required (docs/accesscontrol.md §6.5).
+     */
+    private resolveGroupsFromVariantHashes;
     /**
      * Get a user's public keys from the directory.
      * Used for authentication (signature verification) and encryption (transport encryption).
@@ -55,6 +670,36 @@ export declare class BaseMindooTenantDirectory implements MindooTenantDirectory
         details?: DirectoryUserDetails | null;
     } | null>;
     getUserBySigningPublicKey(publicKey: string): Promise<DirectoryUserLookup | null>;
+    /**
+     * Resolve the full set of signing keys relevant to authenticating a device for
+     * `username` (docs/accesscontrol.md §6.5):
+     *  - `active`: keys currently granted (the device may sync normally), and
+     *  - `wipeRequested`: keys an admin has targeted for remote wipe.
+     *
+     * The two sets are independent: a stolen device may still be active yet
+     * wipe-targeted, or revoked (removed from `active`) yet still wipe-targeted.
+     * The server uses this to let a wipe-targeted (possibly revoked) device
+     * authenticate just far enough to receive the wipe directive.
+     */
+    getUserSigningKeyUniverse(username: string): Promise<{
+        active: string[];
+        wipeRequested: string[];
+    }>;
+    /**
+     * List a user's currently-granted device key pairs (§6.5), each with its
+     * optional label and current remote-wipe status. Returns one entry per
+     * signing key (revoked keys are excluded). Used by admin UIs to pick specific
+     * devices to revoke or relabel. Grant documents are processed oldest→newest,
+     * so the most recent label/encryption key for a signing key wins.
+     */
+    getUserKeyPairs(username: string): Promise<GrantKeyPairInfo[]>;
+    /**
+     * If `signingKey` is the target of an admin-requested remote wipe (§6.5),
+     * return the id of the admin-signed grant document carrying the directive so
+     * the sync server can serve only that document to the targeted device. Returns
+     * null when the key is not wipe-targeted.
+     */
+    getWipeGrantDocId(signingKey: string): Promise<string | null>;
     /**
      * Check if a user has been revoked.
      * A user is considered revoked if they have no active (non-revoked) grant access documents.
@@ -63,10 +708,31 @@ export declare class BaseMindooTenantDirectory implements MindooTenantDirectory
      * @return True if the user has been revoked, false if they have active access
      */
     isUserRevoked(username: string): Promise<boolean>;
-    requestDocHistoryPurge(dbId: string, docId: string, reason: string | undefined, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /**
+     * Publish an admin-signed document-history purge request (docs/accesscontrol.md
+     * §13). Maps an unsigned {@link DocHistoryPurgeRequest} (built in-dialog or
+     * decoded from an `mdb://doc-history-purge/...` URI) to a
+     * {@link DocHistoryPurgeDoc} stored at the fixed id
+     * `acl_dochistorypurge_<requestId>` (one doc per request; append-only audit
+     * record). The doc shell is `$publicinfos`-readable so the sync server can read
+     * the cleartext `dbId` + `docIds` routing fields and execute the purge on its
+     * own stores; only `reason` is encrypted with the tenant `default` key.
+     */
+    publishDocHistoryPurge(request: DocHistoryPurgeRequest, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    /** Parse a raw purge-request doc's data into a {@link DocHistoryPurgeView}. */
+    private toDocHistoryPurgeView;
+    /**
+     * List all purge-request documents at the directory head as
+     * {@link DocHistoryPurgeView}s (decrypting `reason` when the tenant default
+     * key is held; null-tolerant otherwise).
+     */
+    listDocHistoryPurges(): Promise<DocHistoryPurgeView[]>;
+    /** Delete a still-pending purge request document (admin-signed). */
+    deleteDocHistoryPurge(requestId: string, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
     getRequestedDocHistoryPurges(): Promise<Array<{
+        requestId: string;
         dbId: string;
-        docId: string;
+        docIds: string[];
         reason?: string;
         requestedAt: number;
         purgeRequestDocId: string;
@@ -83,18 +749,112 @@ export declare class BaseMindooTenantDirectory implements MindooTenantDirectory
     deleteGroup(groupName: string, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
     getUserNamesList(username: string): Promise<string[]>;
     /**
-     * Compute SHA-256 hash of lowercase username for lookups.
-     * This enables searching for users without exposing the actual username.
+     * Current username-hash scheme version written on new directory documents.
+     * v1 = unsalted `SHA-256(lower(username))` (legacy);
+     * v2 = tenant-salted `SHA-256(tenantId + "/" + lower(username))`;
+     * v3 = tenant-salted over the **NFKC-normalized** lowercase username,
+     *      `SHA-256(tenantId + "/" + lower(NFKC(username)))`.
+     * v3 defends against Unicode homoglyph/normalization tricks (e.g. fullwidth
+     * or decomposed forms that look identical but hash differently), so an
+     * attacker cannot register a visually-equal variant of a privileged name and
+     * have it treated as a distinct identity. See docs/accesscontrol.md §6.5
+     * ("Username hashing"). Matching keeps v1/v2/v3 candidates so documents
+     * written under any prior scheme still resolve (backward compatible).
+     */
+    private static readonly USERNAME_HASH_VERSION;
+    /**
+     * Version of the identity-hash bundle (`identity_hashes`) variant-generation
+     * algorithm (docs/accesscontrol.md §6.5). This is a SEPARATE axis from
+     * {@link USERNAME_HASH_VERSION} (which versions only the hash scheme): it
+     * tracks how completely {@link generateUsernameVariants} enumerated the
+     * DN-hierarchy wildcards. Bump it whenever `generateUsernameVariants` is
+     * extended so readers can detect stale bundles and trigger a backfill.
+     */
+    private static readonly IDENTITY_VARIANTS_VERSION;
+    /**
+     * Compute the precomputed identity-hash bundle for a cleartext username
+     * (docs/accesscontrol.md §6.5): the flattened, deduped v1+v2 hashes of every
+     * DN-hierarchy variant from {@link generateUsernameVariants}. Stored on the
+     * grant doc so the server can match wildcard/group read rules in hash space
+     * without ever holding the cleartext name. Only username variant hashes are
+     * included; group membership stays dynamic (resolved at read time).
+     */
+    private computeIdentityHashes;
+    /**
+     * Legacy (v1) username hash: `SHA-256(lower(username))`, hex-encoded.
+     *
+     * Retained because pre-existing directory documents (and clients that predate
+     * the salted scheme) store this form, and lookups must keep matching them.
      *
      * @param username The username to hash
      * @return The hex-encoded SHA-256 hash of the lowercase username
      */
     private hashUsername;
+    /**
+     * Salted (v2) username hash: `SHA-256(tenantId + "/" + lower(username))`,
+     * hex-encoded. The tenant id salt prevents precomputed/rainbow-table attacks
+     * and cross-tenant hash correlation. New documents write this form
+     * (docs/accesscontrol.md §6.5).
+     */
+    private hashUsernameSalted;
+    /**
+     * NFKC-normalized salted (v3) username hash:
+     * `SHA-256(tenantId + "/" + lower(NFKC(username)))`, hex-encoded. NFKC
+     * canonicalizes Unicode so visually-equivalent or differently-encoded forms
+     * collapse to one hash, blocking homoglyph/normalization impersonation. New
+     * documents write this form. For pure-ASCII usernames it equals v2, so
+     * existing common cases are unaffected.
+     */
+    private hashUsernameSaltedNormalized;
+    /**
+     * The canonical hash to WRITE on new directory documents (currently v3,
+     * NFKC-normalized salted).
+     */
+    private hashUsernameForWrite;
+    /**
+     * All hash forms a given username could be stored as, for MATCHING/lookup.
+     * Returns the legacy (v1), salted (v2) and NFKC-normalized salted (v3) hashes
+     * so that documents written under any scheme are found. Deduplicated.
+     */
+    private usernameHashCandidates;
+    /** Hex-encoded SHA-256 of a UTF-8 string. */
+    private sha256Hex;
     private buildUserDetailsPayload;
     private encryptUserDetailsForTenant;
+    /**
+     * Decrypt the `user_details_encrypted` blob on a grant document. Uses the
+     * shared `_encrypted` / `_encrypted_key` field convention so the key id is
+     * resolved from the optional `user_details_encrypted_key` companion field,
+     * defaulting to the tenant default key for legacy grants that lack it.
+     */
     private decryptUserDetailsForTenant;
     private buildUserLookup;
     private encryptGroupMemberForTenant;
+    /**
+     * Encrypt a rule's cleartext targets (usernames + groups) with the tenant
+     * default key so admin UIs can display who a rule targets without reversing
+     * the salted hashes. Mirrors {@link encryptUserDetailsForTenant}: the blob is
+     * opaque to the sync server (it never holds the tenant key) but readable by
+     * tenant clients. Returns "" when there is nothing cleartext to store (e.g. a
+     * rule authored from raw hashes / pseudo-tokens only).
+     */
+    /**
+     * Resolve a rule's targets (explicit `users_hashes` + named `usernames` /
+     * `groups`) to the salted hash set evaluation matches against. Usernames are
+     * hashed as-is; **group names are normalized (lowercased) first** so they
+     * match the identity set, which hashes the normalized group names returned by
+     * {@link resolveGroupsForUser} (the group cache is keyed by
+     * {@link normalizeGroupName}). Without this, a mixed-case group target like
+     * "Analysts" would never intersect a member's identity (hashed as "analysts").
+     */
+    private resolveRuleTargetHashes;
+    private encryptRuleTargetsForTenant;
+    /**
+     * Decrypt a rule's {@link RuleTargets} display blob. Returns `null` for an
+     * empty/unreadable blob (e.g. a client lacking the tenant default key), in
+     * which case callers fall back to showing the raw `users_hashes`.
+     */
+    private decryptRuleTargetsForTenant;
     private decryptGroupMemberForTenant;
     /**
      * Convert a Uint8Array to a base64 string.