mindoodb 0.0.23 → 0.0.32

package/dist/core/accesscontrol/types.d.ts

@@ -0,0 +1,825 @@
+/**
+ * Access-control directory schema (docs/accesscontrol.md §6) plus the
+ * evaluation result type (§7).
+ *
+ * All access-control state lives in the admin-only `directory` database and
+ * syncs to every participant. Several documents use **fixed document IDs** so
+ * they can be read by direct lookup without an index/view. Every field the
+ * SERVER must evaluate for Tier 1 is encrypted with the `$publicinfos` key (so
+ * the server can read it without the tenant key); `withfields` (Tier 2) is
+ * never readable by the server.
+ */
+/** The `form` value shared by every access-control directory document (§6). */
+export declare const ACCESS_CONTROL_FORM: "accesscontrol";
+/**
+ * Operation types a rule can govern. The `doc_*` mutation types mirror the
+ * relevant `StoreEntryType`s. `doc_read` is special: it is NOT a store entry
+ * type but a **database-level read/sync gate** (§6.6) — it decides whether a
+ * user/group may open and sync a database at all. Because it is the coarse
+ * gate in front of every sync operation for a database, it also gates writes
+ * (a user who cannot read a database cannot create data in it either); `dbid`
+ * is therefore the only scope that matters for a `doc_read` rule, and content
+ * (`withfields`) clauses are not allowed on it.
+ */
+export type RuleType = "doc_create" | "doc_change" | "doc_delete" | "doc_undelete" | "doc_snapshot" | "doc_read";
+/** All valid {@link RuleType} values, for validation and iteration. */
+export declare const RULE_TYPES: readonly RuleType[];
+/** Comparison operators usable in a {@link WithFieldClause}. Closed set. */
+export type Operator = "equals" | "notEquals" | "contains" | "containsAny" | "containsAll" | "exists" | "notExists" | "gt" | "gte" | "lt" | "lte";
+/** All valid {@link Operator} values. */
+export declare const OPERATORS: readonly Operator[];
+/**
+ * Placeholders resolved at evaluation time against the acting user.
+ *
+ * There is deliberately NO `${now}` / wall-clock placeholder: ACL evaluation
+ * must be a pure, deterministic function of the entry plus directory state
+ * (§7, §10), and a wall-clock value would make replicas disagree.
+ */
+export type Placeholder = "${user.username}" | "${user.usernames}" | "${user.groups}";
+/** All valid {@link Placeholder} values. */
+export declare const PLACEHOLDERS: readonly Placeholder[];
+/** Returns true if `value` is a recognized {@link Placeholder}. */
+export declare function isPlaceholder(value: unknown): value is Placeholder;
+/**
+ * Reserved pseudo-tokens stored literally in `users_hashes`. They are NOT
+ * secret (§6.3):
+ * - `$everyone` — all registered users;
+ * - `$admin` — the tenant admin only;
+ * - `$author` — the original creator of the document being modified
+ *   (meaningful only on `doc_change`/`doc_delete`/`doc_undelete`).
+ */
+export declare const PSEUDO_TOKEN_EVERYONE: "$everyone";
+export declare const PSEUDO_TOKEN_ADMIN: "$admin";
+export declare const PSEUDO_TOKEN_AUTHOR: "$author";
+export declare const RESERVED_PSEUDO_TOKENS: readonly string[];
+/** Which document state a {@link WithFieldClause} is evaluated against (§6.3). */
+export type WithFieldWhen = "before" | "after";
+/**
+ * A single content condition inside a Tier 2 rule (§6.3). The presence of any
+ * `withfields` clause on a rule makes the rule Tier 2 (client-only), because it
+ * depends on encrypted document content the server cannot read.
+ */
+export interface WithFieldClause {
+    /** Dot-path inside the document, e.g. `myeditors` or `meta.owner`. */
+    key: string;
+    op: Operator;
+    /** Literal value or a {@link Placeholder} resolved against the acting user. */
+    value: string | number | boolean | string[] | Placeholder;
+    /**
+     * Which document state to evaluate against. Op-appropriate defaults when
+     * omitted: `doc_create` => "after" (no before state exists); all other ops
+     * => "before" (authorization must look at the existing document, otherwise a
+     * user could self-authorize within the same change).
+     */
+    when?: WithFieldWhen;
+}
+/**
+ * The default tenant policy, or a per-database policy (same shape), §6.1/§6.2.
+ *
+ * The mere existence of `acl_defaultpolicy` is what activates access control;
+ * a brand-new tenant has no such document and therefore runs with no checks.
+ * Once the document exists, omitted fields take the stated defaults — see
+ * {@link DEFAULT_POLICY_DEFAULTS} and {@link effectivePolicy}.
+ */
+export interface DefaultAccessPolicyDoc {
+    form: typeof ACCESS_CONTROL_FORM;
+    type: "defaultpolicy";
+    /**
+     * Master off switch (§7 step 0). When true, ALL checks and rules (including
+     * standalone deny rules) are bypassed. Defaults to false when the document
+     * exists.
+     */
+    disableAllAccessChecksAndPolicies?: boolean;
+    denyDocCreate?: boolean;
+    denyDocChange?: boolean;
+    denyDocDelete?: boolean;
+    denyDocUndelete?: boolean;
+    denyDocSnapshot?: boolean;
+    /**
+     * Database read/sync gate (§6.6). When true, members may NOT open or sync the
+     * governed database(s) unless an explicit `doc_read` allow rule grants them
+     * access; when false (the default), reading is open and key possession is the
+     * only thing that decides what a user can actually decrypt.
+     *
+     * This is the coarse per-database gate that sits in front of EVERY sync
+     * operation: a user denied read access can neither pull nor push (so they
+     * cannot create data in the database either — read is required to create).
+     * Like the other `deny<Op>` flags it layers per-db over the tenant default in
+     * {@link effectivePolicy}. The tenant admin is always exempt and the
+     * `"directory"` database is never gated (it must always sync so the policy
+     * itself can be read). Defaults to false.
+     */
+    denyDocRead?: boolean;
+    /**
+     * Optional default `decryptionKeyId` for a `doc_create` that does not specify
+     * one in the governed scope (tenant default, or a single database when set on
+     * a per-db policy). This is NOT a security control: the sync server never
+     * selects keys, so this is a client-side create-time convenience that fills in
+     * the key when the caller omits it (replacing the hardcoded `"default"`
+     * fallback). Which keys a user may create or read under is governed by **key
+     * possession** (the key distribution model, docs/accesscontrol.md §13), not by
+     * a policy gate. Like every policy field it layers per-db over the tenant
+     * default in {@link effectivePolicy}.
+     */
+    defaultCreateKeyId?: string;
+    /**
+     * Governs whether tenant members may open/sync arbitrary database ids.
+     *
+     * This is a **tenant-level** control and is only read from the tenant default
+     * policy (`acl_defaultpolicy`); it is intentionally NOT layered through a
+     * per-db `acl_dbpolicy_*` document. Defaults to `"open"` when omitted.
+     *
+     * - `"open"` (default): any syntactically valid database id may be opened and
+     *   synced — today's behavior, convenient for quick experimentation.
+     * - `"directory-restricted"`: only the `"directory"` database (always
+     *   implicitly allowed) and the ids listed in {@link allowedDbIds} may be
+     *   opened or synced. The tenant admin is exempt and may use any id.
+     */
+    databaseCreationPolicy?: "open" | "directory-restricted";
+    /**
+     * The set of database ids that may be opened/synced when
+     * {@link databaseCreationPolicy} is `"directory-restricted"`. `"directory"` is
+     * always implicitly allowed and need not be listed; every other id (including
+     * `"main"`) must be listed explicitly. Ignored when the policy is `"open"`.
+     * Tenant-level only (not layered per-db).
+     */
+    allowedDbIds?: string[];
+    /**
+     * Storage-format floor: a trusted-time cutoff (ms since epoch) at and after
+     * which a store entry MUST carry the v2 metadata-binding author signature
+     * (`metadataSignature`, `entryVersion >= 2`). Entries whose trusted time is
+     * strictly BEFORE this cutoff may still verify via the legacy ciphertext-only
+     * signature, so genuine older history (and old tenants migrating in) keeps
+     * loading.
+     *
+     * This is a **tenant-level** control read only from the tenant default policy
+     * (`acl_defaultpolicy`); it is NOT layered per-db. Absent = no requirement
+     * (fully backward compatible — the legacy fallback always applies).
+     *
+     * Security model (zero-trust server): the authoritative enforcement is the
+     * sync server's push gate, which compares the cutoff against ITS OWN clock at
+     * ingest (`receivedAt = now`). After the cutoff, no new v1 entry can be
+     * accepted, so a forged v1 entry cannot bypass the floor by backdating its
+     * self-asserted `createdAt`. Honest clients additionally re-check on read
+     * using each entry's {@link entryTrustedTime} as defense in depth. Because the
+     * cutoff lives in the admin-signed policy document, a hostile relay cannot
+     * move it. New tenants are created with this set to their creation time so the
+     * whole tenant is v2-only from entry #1.
+     */
+    requireMetadataSignatureSince?: number;
+}
+/**
+ * The effective baseline defaults when a policy document exists but omits a
+ * field (§6.1). Snapshot and purge default to denied (admin-only).
+ */
+export declare const DEFAULT_POLICY_DEFAULTS: Required<Omit<DefaultAccessPolicyDoc, "form" | "type" | "disableAllAccessChecksAndPolicies" | "defaultCreateKeyId" | "databaseCreationPolicy" | "allowedDbIds" | "requireMetadataSignatureSince">>;
+/** Map a {@link RuleType} to the policy `deny<Op>` field that gates it. */
+export declare const RULE_TYPE_TO_DENY_FIELD: Record<RuleType, keyof typeof DEFAULT_POLICY_DEFAULTS>;
+/** A single access-control rule (§6.3). */
+export interface AclRuleDoc {
+    form: typeof ACCESS_CONTROL_FORM;
+    type: RuleType;
+    /** Stable id, surfaced in {@link AccessDecision.matchedRuleId}. */
+    ruleId: string;
+    description?: string;
+    /** Target database, or `"*"` for all databases in the tenant. */
+    dbid: string | "*";
+    /** Presence makes the rule Tier 2 (client-only). */
+    withfields?: WithFieldClause[];
+    /** User + group hashes, plus reserved pseudo-tokens. */
+    users_hashes: string[];
+    /**
+     * Targeted usernames/groups (JSON {@link RuleTargets}) encrypted with the
+     * tenant default key, base64-encoded — a display aid for admin UIs so they can
+     * show who a rule targets without reversing the salted hashes. Encrypted with
+     * the tenant default key (not `$publicinfos`), so it stays opaque to the sync
+     * server while remaining readable by tenant clients. Empty when the rule was
+     * authored from raw hashes / pseudo-tokens only (nothing cleartext to show).
+     */
+    users_encrypted: string;
+    action: "allow" | "deny";
+}
+/**
+ * Decrypted targets of a rule, for admin-UI display only (never serialized to
+ * the directory). Populated by {@link AclRuleDoc.users_encrypted} on the
+ * listing APIs.
+ */
+export interface RuleTargets {
+    usernames: string[];
+    groups: string[];
+}
+/** A trusted timestamping witness (sync server), §6.4. */
+export interface TrustedWitnessDoc {
+    form: typeof ACCESS_CONTROL_FORM;
+    type: "trustedwitness";
+    /** Ed25519 public key, PEM. */
+    witnessPublicKey: string;
+    serverUrl?: string;
+}
+/** Tier an {@link AccessDecision} was reached at. */
+export type AccessTier = "tier1" | "tier2";
+/** Result of an access-control evaluation (§7). */
+export interface AccessDecision {
+    allowed: boolean;
+    /** Human-readable explanation, for audit logs and the Haven UI. */
+    reason: string;
+    /** Set to the `ruleId` of the rule that decided, when a rule decided. */
+    matchedRuleId?: string;
+    tier: AccessTier;
+}
+/** Singleton id of the tenant default policy document. */
+export declare const ACL_DEFAULT_POLICY_DOC_ID = "acl_defaultpolicy";
+/**
+ * Encode an arbitrary string into a component made only of `[A-Za-z0-9_]`, so
+ * it can be embedded in a fixed document ID that satisfies
+ * {@link CUSTOM_DOC_ID_REGEX} (§6).
+ *
+ * The encoding is injective and reversible: ASCII letters and digits pass
+ * through unchanged; every other byte (including a literal `_`) is escaped as
+ * `_` followed by two lowercase hex digits. Because every literal underscore is
+ * escaped, decoding is unambiguous. Examples:
+ * - `directory` -> `directory`
+ * - `test-db`   -> `test_2ddb`
+ * - `a_b`       -> `a_5fb`
+ */
+export declare function encodeAclIdComponent(raw: string): string;
+/** Inverse of {@link encodeAclIdComponent}. */
+export declare function decodeAclIdComponent(encoded: string): string;
+/** Document id for a per-database policy (§6.2). */
+export declare function aclDbPolicyDocId(dbid: string): string;
+/** Document id for a trusted-witness entry, keyed by witness fingerprint (§6.4). */
+export declare function aclTrustedWitnessDocId(fingerprint: string): string;
+/** Document id for a single rule, keyed by its stable `ruleId` (§6.3). */
+export declare function aclRuleDocId(ruleId: string): string;
+/**
+ * Validate a {@link WithFieldClause} against the closed operator/placeholder
+ * set and the op-specific `when` constraints. Throws a descriptive error on
+ * the first violation. `ruleType` is needed to reject `when: "before"` on
+ * `doc_create` (no before state exists).
+ */
+export declare function validateWithFieldClause(clause: WithFieldClause, ruleType: RuleType): void;
+/**
+ * Validate an {@link AclRuleDoc} (minus the assigned `form`/`ruleId`, which the
+ * directory sets). Enforces the closed type/operator/placeholder sets and the
+ * `withfields` constraints (§6.3). Throws on the first violation.
+ */
+export declare function validateAclRule(rule: {
+    type: RuleType;
+    dbid: string;
+    action: "allow" | "deny";
+    users_hashes: string[];
+    withfields?: WithFieldClause[];
+}): void;
+/**
+ * Validate a {@link DefaultAccessPolicyDoc} (tenant default or per-db) before
+ * it is written. Throws on violation.
+ */
+export declare function validateAccessPolicy(policy: Partial<Omit<DefaultAccessPolicyDoc, "form" | "type">>): void;
+/**
+ * Compute the effective policy by layering DB policy over the tenant default
+ * and filling omitted fields with {@link DEFAULT_POLICY_DEFAULTS} (§6.2, §7).
+ *
+ * Returns a fully-populated set of `deny<Op>` flags plus the master switch.
+ * A `null`/absent default policy means access control was never enabled, which
+ * callers should treat as "all allowed" before calling this.
+ */
+export declare function effectivePolicy(tenantDefault: DefaultAccessPolicyDoc | null | undefined, dbPolicy: DefaultAccessPolicyDoc | null | undefined): Required<Omit<DefaultAccessPolicyDoc, "form" | "type" | "defaultCreateKeyId" | "databaseCreationPolicy" | "allowedDbIds" | "requireMetadataSignatureSince">> & {
+    defaultCreateKeyId?: string;
+};
+/**
+ * Key distribution type tag (the `type` field of a {@link KeyDistributionDoc}).
+ */
+export declare const KEY_DISTRIBUTION_TYPE: "keydistribution";
+/** Key ids that may never be governed by a distribution document. */
+export declare const PROTECTED_DISTRIBUTION_KEY_IDS: readonly string[];
+/**
+ * One distributed version of a key in the {@link KeyDistributionDoc.keyVersions}
+ * manifest. `fingerprint` is the SHA-256 hex of the raw symmetric key bytes and
+ * is the stable identity used to (a) verify unwrapped bytes on import and (b)
+ * scope `pullfrom` deletion to exactly the listed versions. `createdAt` is the
+ * KeyBag version timestamp, used for display and to set the imported version's
+ * stamp.
+ */
+export interface KeyVersionRef {
+    createdAt: number;
+    /** SHA-256 hex of the raw key bytes of this version. */
+    fingerprint: string;
+}
+/**
+ * Wrapped key material for a single recipient device: a map from version
+ * fingerprint to the base64 RSA-OAEP-wrapped raw key bytes of that version.
+ * Every entry must cover ALL of the manifest's version fingerprints (full
+ * coverage), so a recipient can decrypt documents encrypted under any version.
+ */
+export type DeviceWrappedVersions = Record<string, string>;
+/**
+ * The single authoritative document governing the distribution of one symmetric
+ * key (`keyId`). Stored at the fixed id `acl_keydistribution_<keyId>` (singleton
+ * per key); publish is always an upsert of the full desired state.
+ *
+ * The wrapped bytes (`pushto_users_keys`) are produced by a key-*holder* using
+ * each recipient device's RSA encryption public key; the admin merely signs and
+ * writes the document, so an admin outside the recipient set never sees the
+ * plaintext key. Syncing clients reconcile their KeyBags against the head state:
+ * `pushto` users unwrap+verify+merge the manifest's versions; `pullfrom` users
+ * delete exactly the manifest's versions (and purge the scope when nothing
+ * remains). Title/comment/usernames are stored under the `<field>_encrypted`
+ * convention with the tenant `default` key, so the sync server cannot read them;
+ * only the hashes + wrapped material stay `$publicinfos`-readable.
+ */
+export interface KeyDistributionDoc {
+    form: typeof ACCESS_CONTROL_FORM;
+    type: typeof KEY_DISTRIBUTION_TYPE;
+    keyId: string;
+    /** Manifest of distributed versions. fingerprint = SHA-256 hex of raw key bytes. */
+    keyVersions: KeyVersionRef[];
+    title_encrypted: string;
+    title_encrypted_key: string;
+    comment_encrypted?: string;
+    comment_encrypted_key?: string;
+    /** The key-holder's signing public key that wrapped the material (audit trail). */
+    preparedByPublicKey: string;
+    /** Users whose KeyBags receive the key. */
+    pushto_users_hashes: string[];
+    /**
+     * Display aid: ONE encrypted JSON array of usernames, index-aligned with
+     * `pushto_users_hashes`. Single blob so views can read it via
+     * `v.decryptJson("pushto_users_encrypted")` with no view-language extension;
+     * hashes stay authoritative for enforcement, alignment drift is cosmetic.
+     */
+    pushto_users_encrypted?: string;
+    pushto_users_encrypted_key?: string;
+    /**
+     * Wrapped material: `"<userhash>|<deviceEncKeyFingerprint>"` -> { versionFingerprint -> wrappedKey (b64 RSA-OAEP) }.
+     * One entry per active device of each pushto user; every entry covers ALL manifest versions.
+     */
+    pushto_users_keys: Record<string, DeviceWrappedVersions>;
+    /** Users whose KeyBags must NOT hold the manifest's versions (no device keys needed). */
+    pullfrom_users_hashes: string[];
+    pullfrom_users_encrypted?: string;
+    pullfrom_users_encrypted_key?: string;
+}
+/**
+ * One `pushto` recipient inside a {@link KeyDistributionRequest}: the plaintext
+ * username (display only, the URI travels out-of-band) plus the wrapped material
+ * for each of the recipient's active devices.
+ */
+export interface KeyDistributionPushRecipient {
+    username: string;
+    username_hash: string;
+    /** deviceEncKeyFingerprint -> { versionFingerprint -> wrappedKey (b64) }. */
+    devices: Record<string, DeviceWrappedVersions>;
+}
+/**
+ * The full unsigned content of one key's distribution, carried by an
+ * `mdb://key-distribution/...` request URI so a key-holder without admin rights
+ * can hand a ready-to-sign request to an admin. The admin maps it to a
+ * {@link KeyDistributionDoc} on save (encrypting title/comment/usernames and
+ * folding `devices` into `pushto_users_keys`).
+ */
+export interface KeyDistributionRequest {
+    v: 1;
+    tenantId?: string;
+    keyId: string;
+    keyVersions: KeyVersionRef[];
+    /** Plaintext in the URI (sent out-of-band); the admin encrypts it on save. */
+    title: string;
+    comment?: string;
+    preparedByPublicKey: string;
+    pushto: KeyDistributionPushRecipient[];
+    pullfrom: Array<{
+        username: string;
+        username_hash: string;
+    }>;
+}
+/**
+ * Read-side projection of a {@link KeyDistributionDoc} for list/edit UIs. Raw
+ * hashes + wrapped material are surfaced so an editor can preserve devices it
+ * cannot re-wrap; `*Usernames` are the decrypted display arrays (null when the
+ * tenant default key is not held, i.e. the blob is unreadable).
+ */
+export interface KeyDistributionView {
+    keyId: string;
+    title: string | null;
+    comment: string | null;
+    keyVersions: KeyVersionRef[];
+    preparedByPublicKey: string;
+    pushto_users_hashes: string[];
+    pushto_users_keys: Record<string, DeviceWrappedVersions>;
+    pullfrom_users_hashes: string[];
+    pushtoUsernames: string[] | null;
+    pullfromUsernames: string[] | null;
+}
+/** Document id prefix for the per-key distribution documents. */
+export declare const ACL_KEY_DISTRIBUTION_PREFIX = "acl_keydistribution_";
+/**
+ * Document id for a key distribution — a SINGLETON per key id, so there is one
+ * authoritative document governing each key's distribution and publish is always
+ * an upsert. The key id is encoded so arbitrary key ids stay valid doc-id
+ * components.
+ */
+export declare function aclKeyDistributionDocId(keyId: string): string;
+/** True when `docId` is a key-distribution document id. */
+export declare function isKeyDistributionDocId(docId: string): boolean;
+/**
+ * Validate the structural invariants of a key distribution before publish
+ * (docs/accesscontrol.md §13). Throws on the first violation:
+ *
+ *  - `keyId` is non-empty and not a protected id (`default` / `$publicinfos`);
+ *  - `pushto` and `pullfrom` user-hash sets are disjoint;
+ *  - every `pushto` device entry covers EXACTLY the manifest's version
+ *    fingerprints (full coverage, no extras), so every recipient can decrypt
+ *    documents encrypted under any distributed version.
+ *
+ * Grant existence / active-device coverage are enforced by the directory at
+ * publish time (they need directory state), not here.
+ */
+export declare function validateKeyDistribution(input: {
+    keyId: string;
+    keyVersions: KeyVersionRef[];
+    pushto_users_hashes: string[];
+    pullfrom_users_hashes: string[];
+    pushto_users_keys: Record<string, DeviceWrappedVersions>;
+}): void;
+/**
+ * App distribution type tag (the `type` field of an {@link AppDistributionDoc}).
+ */
+export declare const APP_DISTRIBUTION_TYPE: "appdistribution";
+/**
+ * The single authoritative document governing the distribution of one Haven
+ * application (`appId`). Stored at the fixed id `acl_appdistribution_<appId>`
+ * (singleton per app); publish is always an upsert of the full desired state.
+ *
+ * Unlike key distribution there is no cryptographic key material: the payload
+ * is the application registration JSON (`appdata_encrypted`). Recipient
+ * membership (`pushto` / `pullfrom`) is a UX-level governance gesture resolved
+ * client-side at reconcile time against the directory head, with `pullfrom`
+ * winning on any list overlap. Title/comment/appid/version/appdata are stored
+ * under the `<field>_encrypted` convention with the tenant `default` key, so
+ * the sync server cannot read them.
+ */
+export interface AppDistributionDoc {
+    form: typeof ACCESS_CONTROL_FORM;
+    type: typeof APP_DISTRIBUTION_TYPE;
+    /** Bare app id; the document identity (one doc per app). */
+    appId: string;
+    /** Display aid: the app id re-stated under the tenant default key. */
+    appid_encrypted: string;
+    appid_encrypted_key: string;
+    /** The distributed version string (encrypted); drives the reconcile diff. */
+    version_encrypted: string;
+    version_encrypted_key: string;
+    title_encrypted: string;
+    title_encrypted_key: string;
+    comment_encrypted?: string;
+    comment_encrypted_key?: string;
+    /** The application registration JSON payload, encrypted with the default key. */
+    appdata_encrypted: string;
+    appdata_encrypted_key: string;
+    /** The author's signing public key that prepared the distribution (audit). */
+    preparedByPublicKey: string;
+    /** Users whose Haven client should install the app. */
+    pushto_users_hashes: string[];
+    pushto_users_encrypted?: string;
+    pushto_users_encrypted_key?: string;
+    /** Groups whose members should install the app (resolved at reconcile time). */
+    pushto_groups_hashes: string[];
+    pushto_groups_encrypted?: string;
+    pushto_groups_encrypted_key?: string;
+    /** Users whose Haven client must NOT have the app. */
+    pullfrom_users_hashes: string[];
+    pullfrom_users_encrypted?: string;
+    pullfrom_users_encrypted_key?: string;
+    /** Groups whose members must NOT have the app. */
+    pullfrom_groups_hashes: string[];
+    pullfrom_groups_encrypted?: string;
+    pullfrom_groups_encrypted_key?: string;
+}
+/**
+ * The full unsigned content of one app's distribution, built in the authoring
+ * dialog (or carried by an `mdb://app-distribution/...` request URI). The admin
+ * maps it to an {@link AppDistributionDoc} on save (encrypting the display +
+ * payload fields and hashing the user/group names).
+ */
+export interface AppDistributionRequest {
+    v: 1;
+    tenantId?: string;
+    appId: string;
+    version: string;
+    /** Plaintext (encrypted on save). */
+    title: string;
+    comment?: string;
+    /** The application registration JSON payload (serialized + encrypted on save). */
+    appData: unknown;
+    preparedByPublicKey: string;
+    pushtoUsernames: string[];
+    pushtoGroups: string[];
+    pullfromUsernames: string[];
+    pullfromGroups: string[];
+}
+/**
+ * Read-side projection of an {@link AppDistributionDoc} for list/edit UIs. The
+ * `*Usernames` / `*Groups` are the decrypted display arrays (null when the
+ * tenant default key is not held); `appData` is the parsed payload (null when
+ * unreadable).
+ */
+export interface AppDistributionView {
+    appId: string;
+    title: string | null;
+    comment: string | null;
+    version: string | null;
+    appData: unknown | null;
+    preparedByPublicKey: string;
+    pushto_users_hashes: string[];
+    pushto_groups_hashes: string[];
+    pullfrom_users_hashes: string[];
+    pullfrom_groups_hashes: string[];
+    pushtoUsernames: string[] | null;
+    pushtoGroups: string[] | null;
+    pullfromUsernames: string[] | null;
+    pullfromGroups: string[] | null;
+}
+/** One app the active user is entitled to (the install/update side of reconcile). */
+export interface AppDistributionInstall {
+    appId: string;
+    /** The policy's display title — authoritative for the installed app's label. */
+    title: string;
+    version: string;
+    appData: unknown;
+}
+/**
+ * The per-user reconcile plan computed from the directory head: `have` is the
+ * set of apps the user is entitled to (install or update on version change),
+ * `notHave` is the set of distributed app ids the user is NOT entitled to
+ * (remove if locally present).
+ */
+export interface AppDistributionReconcilePlan {
+    have: AppDistributionInstall[];
+    notHave: string[];
+}
+/** Document id prefix for the per-app distribution documents. */
+export declare const ACL_APP_DISTRIBUTION_PREFIX = "acl_appdistribution_";
+/**
+ * Document id for an app distribution — a SINGLETON per app id, so there is one
+ * authoritative document governing each app's distribution and publish is
+ * always an upsert. The app id is encoded so arbitrary ids stay valid doc-id
+ * components.
+ */
+export declare function aclAppDistributionDocId(appId: string): string;
+/** True when `docId` is an app-distribution document id. */
+export declare function isAppDistributionDocId(docId: string): boolean;
+/**
+ * Validate the structural invariants of an app distribution before publish
+ * (docs/accesscontrol.md §13). Throws on the first violation:
+ *
+ *  - `appId` is non-empty;
+ *  - `pushto` and `pullfrom` user-hash sets are disjoint;
+ *  - `pushto` and `pullfrom` group-hash sets are disjoint.
+ */
+export declare function validateAppDistribution(input: {
+    appId: string;
+    pushto_users_hashes: string[];
+    pullfrom_users_hashes: string[];
+    pushto_groups_hashes: string[];
+    pullfrom_groups_hashes: string[];
+}): void;
+/**
+ * Sync setup policy type tag (the `type` field of a {@link SyncSetupPolicyDoc}).
+ */
+export declare const SYNC_SETUP_POLICY_TYPE: "syncsetuppolicy";
+/**
+ * Enforcement mode of a sync setup policy:
+ *  - `"initial"`: the listed databases are seeded onto the targeted user's Sync
+ *    page once; the user remains free to change the sync direction or disable
+ *    them (onboarding aid only).
+ *  - `"permanent"`: the listed databases stay on the Sync page and their sync
+ *    direction is forced to bidirectional; the user cannot change the direction
+ *    or disable them (unless released via `pullfrom`).
+ */
+export type SyncSetupPolicyMode = "initial" | "permanent";
+/** All valid {@link SyncSetupPolicyMode} values, for validation. */
+export declare const SYNC_SETUP_POLICY_MODES: readonly SyncSetupPolicyMode[];
+/**
+ * The authoritative document governing one sync setup policy (`policyId`).
+ * Stored at the fixed id `acl_syncsetuppolicy_<policyId>` (one doc per policy;
+ * a tenant may have several). Publish is always an upsert of the full desired
+ * state.
+ *
+ * Like app distribution there is no key material: the payload is the list of
+ * database ids the targeted clients should have on their Sync page. Recipient
+ * membership (`pushto` / `pullfrom`) is resolved client-side at reconcile time
+ * against the directory head. `pushto` means "targeted" (seed the databases);
+ * `pullfrom` releases any `permanent` lock for that user/group while keeping the
+ * databases seeded (it does NOT remove them). Display fields are stored under
+ * the `<field>_encrypted` convention with the tenant `default` key, so the sync
+ * server cannot read them.
+ */
+export interface SyncSetupPolicyDoc {
+    form: typeof ACCESS_CONTROL_FORM;
+    type: typeof SYNC_SETUP_POLICY_TYPE;
+    /** Bare policy id; the document identity (one doc per policy). */
+    policyId: string;
+    /** Display aid: the policy id re-stated under the tenant default key. */
+    policyid_encrypted: string;
+    policyid_encrypted_key: string;
+    /** Enforcement mode; cleartext is fine (not a secret), but kept simple. */
+    mode: SyncSetupPolicyMode;
+    title_encrypted: string;
+    title_encrypted_key: string;
+    comment_encrypted?: string;
+    comment_encrypted_key?: string;
+    /** JSON array of database ids the targeted clients should sync, encrypted. */
+    databaseids_encrypted: string;
+    databaseids_encrypted_key: string;
+    /** The author's signing public key that prepared the policy (audit). */
+    preparedByPublicKey: string;
+    /** Users whose Haven client should seed the databases. */
+    pushto_users_hashes: string[];
+    pushto_users_encrypted?: string;
+    pushto_users_encrypted_key?: string;
+    /** Groups whose members should seed the databases (resolved at reconcile). */
+    pushto_groups_hashes: string[];
+    pushto_groups_encrypted?: string;
+    pushto_groups_encrypted_key?: string;
+    /** Users for whom any `permanent` lock is released (databases stay seeded). */
+    pullfrom_users_hashes: string[];
+    pullfrom_users_encrypted?: string;
+    pullfrom_users_encrypted_key?: string;
+    /** Groups for whom any `permanent` lock is released. */
+    pullfrom_groups_hashes: string[];
+    pullfrom_groups_encrypted?: string;
+    pullfrom_groups_encrypted_key?: string;
+}
+/**
+ * The full unsigned content of one sync setup policy, built in the authoring
+ * dialog (or carried by an `mdb://sync-setup-policy/...` request URI). The admin
+ * maps it to a {@link SyncSetupPolicyDoc} on save (encrypting the display +
+ * database fields and hashing the user/group names).
+ */
+export interface SyncSetupPolicyRequest {
+    v: 1;
+    tenantId?: string;
+    policyId: string;
+    mode: SyncSetupPolicyMode;
+    /** Plaintext (encrypted on save). */
+    title: string;
+    comment?: string;
+    /** The database ids the targeted clients should sync (encrypted on save). */
+    databaseIds: string[];
+    preparedByPublicKey: string;
+    pushtoUsernames: string[];
+    pushtoGroups: string[];
+    pullfromUsernames: string[];
+    pullfromGroups: string[];
+}
+/**
+ * Read-side projection of a {@link SyncSetupPolicyDoc} for list/edit UIs. The
+ * `*Usernames` / `*Groups` are the decrypted display arrays (null when the
+ * tenant default key is not held); `databaseIds` is the parsed list (null when
+ * unreadable).
+ */
+export interface SyncSetupPolicyView {
+    policyId: string;
+    mode: SyncSetupPolicyMode;
+    title: string | null;
+    comment: string | null;
+    databaseIds: string[] | null;
+    preparedByPublicKey: string;
+    pushto_users_hashes: string[];
+    pushto_groups_hashes: string[];
+    pullfrom_users_hashes: string[];
+    pullfrom_groups_hashes: string[];
+    pushtoUsernames: string[] | null;
+    pushtoGroups: string[] | null;
+    pullfromUsernames: string[] | null;
+    pullfromGroups: string[] | null;
+}
+/** One database the active user should have on the Sync page, with its lock state. */
+export interface SyncSetupPolicyDatabase {
+    databaseId: string;
+    /** True when a `permanent` policy targets this database for the user (and is not released). */
+    locked: boolean;
+}
+/**
+ * The per-user reconcile plan computed from the directory head: the union of
+ * databases the user is targeted for across all policies, each carrying the
+ * effective lock state (locked wins on overlap).
+ */
+export interface SyncSetupPolicyReconcilePlan {
+    databases: SyncSetupPolicyDatabase[];
+}
+/** Document id prefix for the per-policy sync setup policy documents. */
+export declare const ACL_SYNC_SETUP_POLICY_PREFIX = "acl_syncsetuppolicy_";
+/**
+ * Document id for a sync setup policy — one doc per `policyId`, so publish is
+ * always an upsert of that policy's full desired state. The policy id is
+ * encoded so arbitrary ids stay valid doc-id components.
+ */
+export declare function aclSyncSetupPolicyDocId(policyId: string): string;
+/** True when `docId` is a sync-setup-policy document id. */
+export declare function isSyncSetupPolicyDocId(docId: string): boolean;
+/**
+ * Validate the structural invariants of a sync setup policy before publish.
+ * Throws on the first violation:
+ *
+ *  - `policyId` is non-empty;
+ *  - `mode` is a valid {@link SyncSetupPolicyMode};
+ *  - `databaseIds` is non-empty;
+ *  - `pushto` and `pullfrom` user-hash sets are disjoint;
+ *  - `pushto` and `pullfrom` group-hash sets are disjoint.
+ */
+export declare function validateSyncSetupPolicy(input: {
+    policyId: string;
+    mode: SyncSetupPolicyMode;
+    databaseIds: string[];
+    pushto_users_hashes: string[];
+    pullfrom_users_hashes: string[];
+    pushto_groups_hashes: string[];
+    pullfrom_groups_hashes: string[];
+}): void;
+/**
+ * Document history purge request type tag (the `type` field of a
+ * {@link DocHistoryPurgeDoc}).
+ */
+export declare const DOC_HISTORY_PURGE_TYPE: "dochistorypurge";
+/**
+ * The admin-signed document requesting the physical purge of one or more
+ * documents' history from a database. Stored at the fixed id
+ * `acl_dochistorypurge_<requestId>` (one doc per request; append-only audit
+ * record). The doc shell is `$publicinfos`-readable so the server can read the
+ * cleartext `dbId` + `docIds` routing fields and execute the purge; `reason` is
+ * stored under the `<field>_encrypted` convention with the tenant `default` key,
+ * so the server cannot read it.
+ */
+export interface DocHistoryPurgeDoc {
+    form: typeof ACCESS_CONTROL_FORM;
+    type: typeof DOC_HISTORY_PURGE_TYPE;
+    /** Stable request id; the document identity (one doc per request). */
+    requestId: string;
+    /** Cleartext (server-readable) id of the database whose docs are purged. */
+    dbId: string;
+    /** Cleartext (server-readable) ids of the documents to purge. */
+    docIds: string[];
+    /** Optional human-readable reason, encrypted with the tenant default key. */
+    reason_encrypted?: string;
+    reason_encrypted_key?: string;
+    /** The requesting user's signing public key that prepared the request (audit). */
+    preparedByPublicKey: string;
+    /** Epoch millis the request was prepared/signed. */
+    requestedAt: number;
+}
+/**
+ * The full unsigned content of one purge request, built in the authoring dialog
+ * (or carried by an `mdb://doc-history-purge/...` request URI). The admin maps
+ * it to a {@link DocHistoryPurgeDoc} on save (encrypting `reason`). A
+ * `requestId` is generated at prepare time and carried through so admin import +
+ * sign is idempotent (the doc id is derived from it).
+ */
+export interface DocHistoryPurgeRequest {
+    v: 1;
+    tenantId?: string;
+    requestId: string;
+    dbId: string;
+    docIds: string[];
+    /** Plaintext in the URI (sent out-of-band); the admin encrypts it on save. */
+    reason?: string;
+    preparedByPublicKey: string;
+}
+/**
+ * Read-side projection of a {@link DocHistoryPurgeDoc} for list UIs. `reason` is
+ * the decrypted value (null when the tenant default key is not held).
+ */
+export interface DocHistoryPurgeView {
+    requestId: string;
+    dbId: string;
+    docIds: string[];
+    reason: string | null;
+    preparedByPublicKey: string;
+    requestedAt: number;
+    /** The directory document id that carries this request. */
+    purgeRequestDocId: string;
+}
+/** Document id prefix for the per-request purge documents. */
+export declare const ACL_DOC_HISTORY_PURGE_PREFIX = "acl_dochistorypurge_";
+/**
+ * Document id for a purge request — one doc per request, keyed by `requestId`
+ * (append-only audit record). The request id is encoded so arbitrary ids stay
+ * valid doc-id components.
+ */
+export declare function aclDocHistoryPurgeDocId(requestId: string): string;
+/** True when `docId` is a purge-request document id. */
+export declare function isDocHistoryPurgeDocId(docId: string): boolean;
+/**
+ * Validate the structural invariants of a purge request before publish. Throws
+ * on the first violation:
+ *
+ *  - `requestId` is non-empty;
+ *  - `dbId` is non-empty;
+ *  - `docIds` is a non-empty array of non-empty strings.
+ */
+export declare function validateDocHistoryPurge(input: {
+    requestId: string;
+    dbId: string;
+    docIds: string[];
+}): void;
+//# sourceMappingURL=types.d.ts.map