@docstack/client 0.2.0 → 0.3.0

package/lib/index.js

@@ -3703,7 +3703,43 @@ const sys_017 = {
         }
     ]
 };
-syspatches.push(sys_011, sys_012, sys_013, sys_014, sys_015, sys_016, sys_017);
+/**
+ * Cryptographic access scopes arrive; the JS-rule policy engine retires
+ * (ADR-0045, spec 02). `~AccessScope` is the carrier of the ONE access-control
+ * language: a scope's CEK travels ABE-sealed under its attribute formula, and
+ * denial is decryption failure - nothing evaluates rules anymore. The three
+ * seeded `~Policy` documents are deactivated in place: nothing reads them, and
+ * an inert-but-active policy would misstate what governs access. Their class
+ * stays for legacy data.
+ */
+const sys_018 = {
+    "_id": "~sys-0.0.18",
+    "~class": "patch",
+    "version": "0.0.18",
+    "target": "system",
+    "changelog": "### Schema Patch: v0.0.18\\n#### New Class: ~AccessScope (cryptographic access, ADR-0045)\\n#### Deactivated: seeded ~Policy documents (policy engine retired)",
+    "docs": [
+        {
+            "_id": "~AccessScope",
+            "~class": "class",
+            "active": true,
+            "name": "AccessScope",
+            "description": "A named set of content sealed under one CEK, itself ABE-encrypted under the scope's attribute policy (ADR-0045)",
+            "schema": {
+                "scopeId": { "name": "scopeId", "type": "string", "config": { "mandatory": true } },
+                "policyString": { "name": "policyString", "type": "string", "config": { "mandatory": true } },
+                "abeWrappedCek": { "name": "abeWrappedCek", "type": "string", "config": { "mandatory": true } },
+                "kid": { "name": "kid", "type": "string", "config": { "mandatory": true, "maxLength": 16 } },
+                "version": { "name": "version", "type": "integer", "config": { "mandatory": true } },
+                "encryptedMarker": { "name": "encryptedMarker", "type": "object", "config": { "mandatory": true } }
+            }
+        },
+        { "_id": "Policy-System-Classes", "_rev": "auto", "~class": "~Policy", "active": false },
+        { "_id": "Policy-Admin", "_rev": "auto", "~class": "~Policy", "active": false },
+        { "_id": "Policy-User-SelfAccess", "_rev": "auto", "~class": "~Policy", "active": false }
+    ]
+};
+syspatches.push(sys_011, sys_012, sys_013, sys_014, sys_015, sys_016, sys_017, sys_018);
 /**
  * Every document id the system patches seed.
  *
@@ -3760,11 +3796,33 @@ const logger$4 = createLogger().child({ module: "pouchdb" });
  * ```
  */
 class StackLockedError extends Error {
-    constructor(className) {
-        super(`Stack is locked: '${className}' has encrypted attributes and no document key has been supplied, ` +
-            `so writing it would store those fields in the clear. Call 'stack.unlock(documentKey)' first.`);
+    constructor(className, scopeId) {
+        super(scopeId
+            ? `Scope '${scopeId}' is sealed: '${className}' has encrypted attributes and the keyring holds no ` +
+                `read-write key for the scope, so writing would seal under the wrong key or none. ` +
+                `Call 'stack.unlockScopes(attributeKey)' first.`
+            : `Stack is locked: '${className}' has encrypted attributes and no document key has been supplied, ` +
+                `so writing it would store those fields in the clear. Call 'stack.unlock(documentKey)' first.`);
         this.name = "StackLockedError";
         this.className = className;
+        this.scopeId = scopeId;
+    }
+}
+/**
+ * A write whose `~scope` label disagrees with its sealed payloads' key ids
+ * (spec 02 §2.3 rule 2). Refused, never repaired: re-sealing content the
+ * writer could not open under the labeled scope's key is exactly the
+ * induced-downgrade attack a tampered label is fishing for. A legitimate
+ * relabel opens the original scope first, so its payloads arrive as plaintext.
+ */
+class StackScopeMismatchError extends Error {
+    constructor(docId, scopeId, kid) {
+        super(`Document '${docId}' is labeled scope '${scopeId}' but carries a sealed payload under key ` +
+            `'${kid !== null && kid !== void 0 ? kid : "(unstamped)"}' that does not belong to the scope. Refusing to write: relabeling ` +
+            `requires the original scope open, and a mismatch is quarantined, never re-sealed (ADR-0045).`);
+        this.name = "StackScopeMismatchError";
+        this.docId = docId;
+        this.scopeId = scopeId;
     }
 }
 /**
@@ -4128,14 +4186,44 @@ const StackPlugin = (pouch, stack, pristine) => {
                             }
                             classCache.set(className, classObj);
                             const encryptableAttributes = classObj.getEncryptedAttributes();
-                            // A locked stack has no key, so encrypting is impossible and the
-                            // fields would land in the clear. Refuse instead of degrading:
-                            // silent plaintext is the failure mode ADR-0018 exists to remove.
-                            // Bootstrap patches are the documented exception - the seed system
+                            // A sealed key cannot encrypt. Refuse instead of degrading:
+                            // silent plaintext is the failure mode ADR-0018 exists to remove,
+                            // and sealing under the WRONG key is its ADR-0045 sibling. A
+                            // scope-labeled document answers to its scope's CEK; an
+                            // unlabeled one to the legacy document key. Bootstrap patches
+                            // are the documented legacy-path exception - the seed system
                             // user has to exist before any key can be recovered, and
                             // `rekeyBootstrapDocuments` encrypts it once one arrives.
-                            if (encryptableAttributes.length && stack.isLocked() && !(options === null || options === void 0 ? void 0 : options.isPatch)) {
-                                throw new StackLockedError(className);
+                            if (encryptableAttributes.length && stack.cryptoEngine.isEnabled()) {
+                                const scopeLabel = stack.resolveScopeLabel(doc, classObj.model);
+                                if (scopeLabel) {
+                                    if (!stack.cryptoEngine.isScopeWritable(scopeLabel)) {
+                                        throw new StackLockedError(className, scopeLabel);
+                                    }
+                                    // The label↔kid mismatch guard (spec 02 §2.3 rule 2),
+                                    // checked here beside the lock refusal so both are the
+                                    // same pre-write rejection: a payload already sealed
+                                    // under a key OUTSIDE the labeled scope is a relabel the
+                                    // writer could not have performed legitimately (it never
+                                    // opened the source), so it is refused - never re-sealed
+                                    // under the labeled key, which is the induced downgrade.
+                                    const scopeKids = await stack.getAccessScopeKids(scopeLabel);
+                                    if (!scopeKids) {
+                                        throw new StackScopeMismatchError(doc._id, scopeLabel, undefined);
+                                    }
+                                    for (const attribute of encryptableAttributes) {
+                                        const value = doc[attribute.getName()];
+                                        if (value && typeof value === "object" && value.__enc === true) {
+                                            const kid = value.kid;
+                                            if (!kid || !scopeKids.has(kid)) {
+                                                throw new StackScopeMismatchError(doc._id, scopeLabel, kid);
+                                            }
+                                        }
+                                    }
+                                }
+                                else if (stack.isLocked() && !(options === null || options === void 0 ? void 0 : options.isPatch)) {
+                                    throw new StackLockedError(className);
+                                }
                             }
                             if (stack.cryptoEngine.isEnabled() && encryptableAttributes.length) {
                                 await stack.cryptoEngine.decryptDocument(doc, classObj);
@@ -4230,7 +4318,11 @@ const StackPlugin = (pouch, stack, pristine) => {
                         }
                         classCache.set(className, classObj);
                         const clone = Object.assign({}, doc);
-                        await stack.cryptoEngine.encryptDocument(clone, classObj);
+                        // The label was validated in the pre-write guard above
+                        // (scope known, writable, no foreign-kid payloads); here it
+                        // only selects the sealing key.
+                        const scopeLabel = stack.resolveScopeLabel(clone, classObj.model);
+                        await stack.cryptoEngine.encryptDocument(clone, classObj, scopeLabel);
                         return clone;
                     }
                 }
@@ -8676,300 +8768,6 @@ class JobScheduler {
     }
 }
 
-/**
- * Set of system classes that bypass policy evaluation.
- * These classes are internal to DocStack and always accessible.
- */
-const SYSTEM_CLASSES = new Set([
-    "~Policy",
-    "~Job",
-    "~JobRun",
-    "~AuthModule",
-    "~UserSession",
-    "class",
-    "domain"
-]);
-/**
- * Engine for evaluating access control policies on documents.
- *
- * PolicyEngine implements role-based access control (RBAC) by evaluating
- * policy rules against documents and user sessions. Policies can be:
- * - Class-level (apply to all documents of a class)
- * - User-specific (apply only to a specific user)
- * - Group-specific (apply only to users in a specific group)
- *
- * Policy rules are JavaScript expressions that receive the document,
- * session, and groupId as context and return a boolean.
- *
- * @example
- * ```typescript
- * // Policy engine is used automatically during document operations
- * // Policies are defined as documents:
- * await stack.createDoc(null, '~Policy', null, {
- *     name: 'user-read-own',
- *     targetClass: ['User'],
- *     rule: 'return document.userId === session.userId;'
- * });
- * ```
- */
-class PolicyEngine {
-    /**
-     * Creates a new PolicyEngine instance.
-     * @param stack - The parent ClientStack instance
-     */
-    constructor(stack) {
-        /**
-         * Every `~Policy` document, loaded once and reused across evaluations.
-         *
-         * `isReadableDocument` runs once per document a read returns, and it used to re-fetch
-         * the policy list from the database each time - the dominant cost of every read path.
-         * The list is invalidated on any write that touches a `~Policy` document: the write
-         * path calls {@link invalidatePolicyCache} synchronously (see StackPlugin), and the
-         * stack's shared changes feed calls it again for out-of-band writes such as another
-         * tab's. `null` means not loaded.
-         */
-        this.allPoliciesCache = null;
-        /**
-         * Compiled policy rules, keyed by their source text.
-         *
-         * A rule is evaluated once per policy per document, and `new Function` is a full
-         * compile each time. The source text is the key - not the policy id - so two policies
-         * sharing a rule share the compilation, and an edited rule is simply a new key.
-         */
-        this.compiledRules = new Map();
-        this.stack = stack;
-    }
-    /**
-     * Drops the cached policy list so the next evaluation re-reads it.
-     * Called by the write path and the changes feed whenever a `~Policy` document lands.
-     */
-    invalidatePolicyCache() {
-        this.allPoliciesCache = null;
-    }
-    /**
-     * Gets the current authentication session proof.
-     * @returns The session proof, or undefined if not authenticated
-     */
-    getSessionProof() {
-        return this.stack.authSession;
-    }
-    /**
-     * Checks if a class should bypass policy evaluation.
-     * System classes (prefixed with ~) are always allowed.
-     *
-     * @param targetClass - The class name to check
-     * @returns `true` if the class should bypass policies
-     */
-    shouldBypass(targetClass) {
-        if (SYSTEM_CLASSES.has(targetClass))
-            return true;
-        const normalized = targetClass.startsWith("~") ? targetClass.slice(1) : `~${targetClass}`;
-        return SYSTEM_CLASSES.has(normalized);
-    }
-    async loadPolicies(targetClass, aliases = []) {
-        const identifiers = new Set([targetClass, ...aliases]);
-        if (this.allPoliciesCache === null) {
-            // Read raw rather than through `findDocuments`: policies are a system class
-            // that bypasses policy evaluation anyway, and going through the read path
-            // here recursed into a policy check per policy document. The selector is the
-            // same one `findDocuments` produced (it injects `active: true`), and that is
-            // the contract, not an accident: a policy enforces only while `active: true`,
-            // exactly as a document is visible only while active - an unflagged or
-            // explicitly inactive policy does not apply (ADR-0032). The explicit limit is
-            // because pouchdb-find otherwise silently caps results at 25, which for
-            // policies means silently not enforcing the 26th.
-            const result = await this.stack.db.find({
-                selector: { "~class": "~Policy", active: true },
-                limit: 2 ** 31 - 1,
-            });
-            this.allPoliciesCache = result.docs;
-        }
-        return this.allPoliciesCache.filter((doc) => {
-            if (!Array.isArray(doc.targetClass))
-                return false;
-            return doc.targetClass.some((entry) => identifiers.has(entry));
-        });
-    }
-    getTargetIdentifiers(targetId, targetName) {
-        const identifiers = new Set();
-        const variants = [targetId, targetName];
-        for (const value of variants) {
-            identifiers.add(value);
-            if (value.startsWith("~")) {
-                identifiers.add(value.slice(1));
-            }
-            else {
-                identifiers.add(`~${value}`);
-            }
-        }
-        return Array.from(identifiers);
-    }
-    async resolveClassTarget(targetClass) {
-        var _a, _b;
-        const classModel = await this.stack.getClassModel(targetClass).catch(() => null);
-        return {
-            id: (_a = classModel === null || classModel === void 0 ? void 0 : classModel._id) !== null && _a !== void 0 ? _a : targetClass,
-            name: (_b = classModel === null || classModel === void 0 ? void 0 : classModel.name) !== null && _b !== void 0 ? _b : targetClass,
-        };
-    }
-    /**
-     * Evaluates a policy rule against a document and session.
-     * The rule is a JavaScript expression that returns a boolean.
-     *
-     * @param policy - The policy containing the rule
-     * @param document - The document being accessed
-     * @param session - The current auth session
-     * @returns Whether the rule permits access
-     */
-    async evaluateRule(policy, document, session) {
-        let executor = this.compiledRules.get(policy.rule);
-        if (!executor) {
-            executor = new Function("document", "session", "groupId", `"use strict"; ${policy.rule}`);
-            this.compiledRules.set(policy.rule, executor);
-        }
-        const result = executor(document || {}, session.session, session.session.groupId);
-        if (result instanceof Promise) {
-            return Boolean(await result);
-        }
-        return Boolean(result);
-    }
-    filterPoliciesForSession(policies, session) {
-        const sessionUserId = session.session.userId || session.session.username;
-        const sessionGroups = Array.isArray(session.session.groupId)
-            ? session.session.groupId
-            : session.session.groupId
-                ? [session.session.groupId]
-                : [];
-        return policies.filter((policy) => {
-            const matchesUser = !policy.userId || policy.userId === sessionUserId || policy.userId === session.session.username;
-            const matchesGroup = !policy.groupId || sessionGroups.includes(policy.groupId);
-            return matchesUser && matchesGroup;
-        });
-    }
-    async authorize(targetClass, operation, document) {
-        const { id: targetId, name: targetName } = await this.resolveClassTarget(targetClass);
-        const identifiers = this.getTargetIdentifiers(targetId, targetName);
-        if (this.shouldBypass(targetName)) {
-            return true;
-        }
-        const policies = await this.loadPolicies(targetId, identifiers);
-        if (policies.length === 0) {
-            return true;
-        }
-        const session = this.getSessionProof();
-        if (!session) {
-            throw new Error("Stack is not authenticated for policy evaluation");
-        }
-        const targetedPolicies = policies.filter((policy) => policy.userId || policy.groupId);
-        const basePolicies = policies.filter((policy) => !policy.userId && !policy.groupId);
-        const matchingPolicies = targetedPolicies.length > 0
-            ? this.filterPoliciesForSession(targetedPolicies, session)
-            : this.filterPoliciesForSession(basePolicies, session);
-        if (targetedPolicies.length > 0 && matchingPolicies.length === 0) {
-            throw new Error(`No matching policy allowed ${operation} on class '${targetClass}'`);
-        }
-        let allowed = false;
-        for (const policy of matchingPolicies) {
-            const result = await this.evaluateRule(policy, document, session);
-            if (result === false) {
-                throw new Error(`Policy '${policy._id}' denied ${operation} on class '${targetClass}'`);
-            }
-            if (result === true) {
-                allowed = true;
-            }
-        }
-        return allowed;
-    }
-    /**
-     * Whether any policy applies to a class - i.e. whether reads of it are filtered.
-     *
-     * Lets the query engine know when a database-level LIMIT is safe: with no
-     * applicable policies, no row fetched within the limit can be dropped afterwards.
-     * Cheap once the policy list is cached.
-     *
-     * @param targetClass - The class name or id.
-     * @returns `true` if at least one policy targets the class.
-     */
-    async hasPoliciesFor(targetClass) {
-        const { id: targetId, name: targetName } = await this.resolveClassTarget(targetClass);
-        if (this.shouldBypass(targetName))
-            return false;
-        const policies = await this.loadPolicies(targetId, this.getTargetIdentifiers(targetId, targetName));
-        return policies.length > 0;
-    }
-    /**
-     * Ensures write access is allowed for a document of the given class.
-     * Throws an error if no policy permits the write operation.
-     *
-     * @param targetClass - The class of the document being written
-     * @param document - The document to write
-     * @throws Error if write is not permitted
-     *
-     * @example
-     * ```typescript
-     * // Called automatically during createDoc/updateCard operations
-     * await policyEngine.ensureWriteAllowed('Task', taskDocument);
-     * ```
-     */
-    async ensureWriteAllowed(targetClass, document) {
-        const allowed = await this.authorize(targetClass, "write", document);
-        if (!allowed) {
-            throw new Error(`No matching policy allowed write on class '${targetClass}'`);
-        }
-    }
-    /**
-     * Checks if a document is readable by the current user.
-     * Used to filter query results based on read policies.
-     *
-     * @param document - The document to check
-     * @returns `true` if the document can be read
-     * @throws Error if the stack is not authenticated
-     *
-     * @example
-     * ```typescript
-     * // Used internally during findDocuments
-     * const readable = await policyEngine.isReadableDocument(doc);
-     * if (readable) {
-     *     results.push(doc);
-     * }
-     * ```
-     */
-    async isReadableDocument(document) {
-        const targetClass = document === null || document === void 0 ? void 0 : document["~class"];
-        const { id: targetId, name: targetName } = await this.resolveClassTarget(targetClass);
-        if (!targetClass || this.shouldBypass(targetName)) {
-            return true;
-        }
-        const policies = await this.loadPolicies(targetId, this.getTargetIdentifiers(targetId, targetName));
-        if (policies.length === 0) {
-            return true;
-        }
-        const session = this.getSessionProof();
-        if (!session) {
-            throw new Error("Stack is not authenticated for policy evaluation");
-        }
-        const targetedPolicies = policies.filter((policy) => policy.userId || policy.groupId);
-        const basePolicies = policies.filter((policy) => !policy.userId && !policy.groupId);
-        const matchingPolicies = targetedPolicies.length > 0
-            ? this.filterPoliciesForSession(targetedPolicies, session)
-            : this.filterPoliciesForSession(basePolicies, session);
-        if (targetedPolicies.length > 0 && matchingPolicies.length === 0) {
-            return false;
-        }
-        let permitted = false;
-        for (const policy of matchingPolicies) {
-            const result = await this.evaluateRule(policy, document, session);
-            if (result === false) {
-                return false;
-            }
-            if (result === true) {
-                permitted = true;
-            }
-        }
-        return permitted;
-    }
-}
-
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 const getCrypto = () => globalThis.crypto;
@@ -9037,12 +8835,23 @@ const deriveKeyId = async (hexKey) => {
         .map(b => b.toString(16).padStart(2, "0"))
         .join("");
 };
-const encryptWithAesGcm = async (plaintext, key, kid) => {
+/**
+ * The additional-authenticated-data string binding a scope-sealed payload to
+ * its label (spec 02 §2.3 rule 3): decryption derives it from the DOCUMENT's
+ * `~scope` at read time, so a tampered or stripped label does not merely look
+ * inconsistent - the GCM authentication fails and the payload stays sealed.
+ * Legacy-key payloads pass no AAD, keeping pre-scope ciphertext readable.
+ */
+const scopeAad = (scopeId, kid) => `${scopeId}|${kid}`;
+const encryptWithAesGcm = async (plaintext, key, kid, aad) => {
     const cryptoObj = getCrypto();
     const iv = new Uint8Array(12);
     cryptoObj.getRandomValues(iv);
     const ivBuffer = iv.buffer.slice(iv.byteOffset, iv.byteOffset + iv.byteLength);
-    const ciphertext = await cryptoObj.subtle.encrypt({ name: "AES-GCM", iv: ivBuffer }, key, encoder.encode(plaintext));
+    const params = { name: "AES-GCM", iv: ivBuffer };
+    if (aad)
+        params.additionalData = encoder.encode(aad);
+    const ciphertext = await cryptoObj.subtle.encrypt(params, key, encoder.encode(plaintext));
     const payload = {
         __enc: true,
         iv: toBase64(iv),
@@ -9053,18 +8862,23 @@ const encryptWithAesGcm = async (plaintext, key, kid) => {
         payload.kid = kid;
     return payload;
 };
-const decryptWithAesGcm = async (payload, key) => {
+const decryptWithAesGcm = async (payload, key, aad) => {
     const cryptoObj = getCrypto();
     const ivBytes = fromBase64(payload.iv);
     const dataBytes = fromBase64(payload.data);
     const ivBuffer = ivBytes.buffer.slice(ivBytes.byteOffset, ivBytes.byteOffset + ivBytes.byteLength);
     const dataBuffer = dataBytes.buffer.slice(dataBytes.byteOffset, dataBytes.byteOffset + dataBytes.byteLength);
-    const decrypted = await cryptoObj.subtle.decrypt({ name: "AES-GCM", iv: ivBuffer }, key, dataBuffer);
+    const params = { name: "AES-GCM", iv: ivBuffer };
+    if (aad)
+        params.additionalData = encoder.encode(aad);
+    const decrypted = await cryptoObj.subtle.decrypt(params, key, dataBuffer);
     return decoder.decode(decrypted);
 };
 const wrapDocumentKey = async (documentKey, derivedKeyHex) => {
     const key = await importAesKeyFromHex(derivedKeyHex);
-    const payload = await encryptWithAesGcm(documentKey, key);
+    // Stamped with the WRAPPED key's id, so wrapped key material is
+    // self-identifying (spec 02 §3): a user record can say which key it holds.
+    const payload = await encryptWithAesGcm(documentKey, key, await deriveKeyId(documentKey));
     return JSON.stringify(payload);
 };
 const unwrapDocumentKey = async (wrappedDocumentKey, cryptoKey, derivedKeyHex) => {
@@ -9127,6 +8941,18 @@ class CryptoEngine {
          * interrupted, and resumed.
          */
         this.retiredKeys = new Map();
+        /**
+         * Scope CEKs admitted by {@link admitScopeKey}, by key id (ADR-0045).
+         *
+         * The keyring the single document key generalizes into: reads dispatch by a
+         * payload's `kid` across the legacy key, retired keys, and these; writes
+         * into a scope-labeled document select through {@link scopeWriteKeys}. A
+         * scope whose CEK is absent here is simply LOCKED - its payloads stay
+         * sealed, which is the access decision.
+         */
+        this.scopeKeys = new Map();
+        /** The read-write entry per scope id - the CEK that seals new writes. */
+        this.scopeWriteKeys = new Map();
         this.logger = createLogger().child({ module: "crypto-engine" });
         this.stack = stack;
         this.enabled = !stack.isCryptoEngineDisabled();
@@ -9206,8 +9032,94 @@ class CryptoEngine {
         return [
             ...(this.documentKeyId ? [this.documentKeyId] : []),
             ...this.retiredKeys.keys(),
+            ...this.scopeKeys.keys(),
         ];
     }
+    /**
+     * Admits a scope's CEK into the keyring after its canary verified
+     * (spec 02 §2.1 - admission is the caller's `verifyScopeCek` first, this
+     * second). The winning version of a scope enters read-write and becomes
+     * the key new writes into the scope seal under; older versions enter
+     * read-only, the retired-keys discipline applied per scope.
+     *
+     * @returns The admitted key's id.
+     */
+    async admitScopeKey(scopeId, cekHex, version, mode) {
+        if (!this.enabled)
+            throw new Error("Crypto engine is disabled");
+        const kid = await deriveKeyId(cekHex);
+        const entry = {
+            kid,
+            cryptoKey: await importAesKeyFromHex(cekHex, mode === "read-write" ? ["encrypt", "decrypt"] : ["decrypt"]),
+            scopeId,
+            version,
+            mode,
+        };
+        this.scopeKeys.set(kid, entry);
+        if (mode === "read-write") {
+            const current = this.scopeWriteKeys.get(scopeId);
+            if (!current || current.version <= version) {
+                if (current && current.kid !== kid) {
+                    // Superseded by a higher rotation version: keep it readable.
+                    this.scopeKeys.set(current.kid, Object.assign(Object.assign({}, current), { mode: "read-only" }));
+                }
+                this.scopeWriteKeys.set(scopeId, entry);
+            }
+            else {
+                // A lower version arriving late reads, never writes.
+                this.scopeKeys.set(kid, Object.assign(Object.assign({}, entry), { mode: "read-only" }));
+            }
+        }
+        return kid;
+    }
+    /**
+     * Tests a candidate CEK against a scope's canary WITHOUT admitting it -
+     * the ADR-0018 admission discipline per scope: a corrupted or
+     * rotated-away ciphertext is an error at unlock, not garbage later. The
+     * marker's AAD binds it to the scope and key it was minted for.
+     */
+    async verifyScopeCek(scopeId, cekHex, marker) {
+        if (!this.enabled)
+            return false;
+        if (!isEncryptedPayload(marker))
+            return false;
+        try {
+            const kid = await deriveKeyId(cekHex);
+            const key = await importAesKeyFromHex(cekHex, ["decrypt"]);
+            await decryptWithAesGcm(marker, key, scopeAad(scopeId, kid));
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    }
+    /** Whether new writes into this scope can seal - a read-write CEK is held. */
+    isScopeWritable(scopeId) {
+        return this.enabled && this.scopeWriteKeys.has(scopeId);
+    }
+    /** Scope ids holding a read-write CEK. */
+    unlockedScopeIds() {
+        return this.enabled ? [...this.scopeWriteKeys.keys()] : [];
+    }
+    /** The key id new writes into a scope seal under, when the scope is open. */
+    getScopeWriteKeyId(scopeId) {
+        var _a;
+        return (_a = this.scopeWriteKeys.get(scopeId)) === null || _a === void 0 ? void 0 : _a.kid;
+    }
+    /** The scope a held key id belongs to, if it is a scope key. */
+    scopeOfKid(kid) {
+        var _a;
+        return (_a = this.scopeKeys.get(kid)) === null || _a === void 0 ? void 0 : _a.scopeId;
+    }
+    /**
+     * Drops every admitted scope CEK - the session's material is gone, the
+     * scopes are locked again. Mirrors what clearing the document key does for
+     * the legacy path.
+     */
+    dropScopeKeys() {
+        this.scopeKeys.clear();
+        this.scopeWriteKeys.clear();
+    }
     /**
      * Generates a cryptographically secure random string.
      * Useful for generating salts or nonces.
@@ -9309,22 +9221,29 @@ class CryptoEngine {
         return this.cryptoKey;
     }
     /**
-     * Chooses the key that can open a payload.
+     * Chooses the keyring entry that can open a payload.
      *
      * A payload names its key, so an old field found mid-re-key is decrypted with the key
      * it was actually written under instead of failing against the current one. Payloads
-     * from before identifiers existed name nothing, and are tried against the current key
-     * - which is what they meant when only one key could exist.
+     * from before identifiers existed name nothing, and are tried against the LEGACY
+     * document key only (spec 02 §3): under multiple keys, falling back to "whatever is
+     * current" would silently mis-route - a scope key never answers for an unnamed
+     * payload.
      */
-    async resolveKeyFor(payload, fallback) {
-        var _a;
-        if (!payload.kid)
-            return fallback;
-        if (payload.kid === this.documentKeyId)
-            return fallback;
-        return (_a = this.retiredKeys.get(payload.kid)) !== null && _a !== void 0 ? _a : null;
+    async resolveEntryFor(payload) {
+        if (!payload.kid || payload.kid === this.documentKeyId) {
+            const legacy = await this.getCryptoKey();
+            return legacy ? { key: legacy } : null;
+        }
+        const retired = this.retiredKeys.get(payload.kid);
+        if (retired)
+            return { key: retired };
+        const scope = this.scopeKeys.get(payload.kid);
+        if (scope)
+            return { key: scope.cryptoKey, scope };
+        return null;
     }
-    async encryptValue(value, key) {
+    async encryptValue(value, key, kid, aad) {
         if (!this.enabled)
             return value;
         if (!key)
@@ -9334,26 +9253,38 @@ class CryptoEngine {
         if (isEncryptedPayload(value))
             return value;
         const serialized = JSON.stringify(value);
-        return encryptWithAesGcm(serialized, key, this.documentKeyId);
+        return encryptWithAesGcm(serialized, key, kid !== null && kid !== void 0 ? kid : this.documentKeyId, aad);
     }
-    async decryptValue(value, key) {
+    /**
+     * @param label - The document's `~scope` at read time. A scope-sealed
+     * payload authenticates against it (AAD, spec 02 §2.3 rule 3): a tampered
+     * or stripped label fails the GCM authentication and the payload stays
+     * sealed - the mismatch is detected, never silently honored.
+     */
+    async decryptValue(value, label) {
         if (!this.enabled)
             return value;
-        if (!key)
-            return value;
         if (!isEncryptedPayload(value))
             return value;
-        const resolved = await this.resolveKeyFor(value, key);
+        const resolved = await this.resolveEntryFor(value);
         if (!resolved) {
             this.logger.warn("No held key matches this payload; leaving it encrypted", { kid: value.kid });
             return value;
         }
+        const aad = resolved.scope ? scopeAad(label !== null && label !== void 0 ? label : "", value.kid) : undefined;
         try {
-            const decrypted = await decryptWithAesGcm(value, resolved);
+            const decrypted = await decryptWithAesGcm(value, resolved.key, aad);
             return JSON.parse(decrypted);
         }
         catch (error) {
-            this.logger.error("Failed to decrypt value", { error: (error === null || error === void 0 ? void 0 : error.message) || error });
+            if (resolved.scope) {
+                this.logger.warn("Scope payload does not authenticate against the document's label; leaving it sealed", {
+                    kid: value.kid, scopeOfKey: resolved.scope.scopeId, label: label !== null && label !== void 0 ? label : null,
+                });
+            }
+            else {
+                this.logger.error("Failed to decrypt value", { error: (error === null || error === void 0 ? void 0 : error.message) || error });
+            }
             return value;
         }
     }
@@ -9388,23 +9319,46 @@ class CryptoEngine {
      * @param document - The document to encrypt
      * @param classObj - The class defining which fields to encrypt
      */
-    async encryptDocument(document, classObj) {
+    /**
+     * @param scopeId - The document's resolved scope label. When present, the
+     * scope's read-write CEK seals every attribute (stamped with its `kid`,
+     * bound to the label via AAD); the caller has already refused the write if
+     * the scope is not open. Absent, the legacy document key path applies
+     * unchanged.
+     */
+    async encryptDocument(document, classObj, scopeId) {
         var _a, _b, _c;
         if (!this.enabled)
             return;
         const encryptableAttributes = classObj.getEncryptedAttributes();
         if (!encryptableAttributes.length)
             return;
-        const key = await this.getCryptoKey();
-        if (!key) {
-            this.logger.warn("Document key is not available; skipping encryption", { className: (_b = (_a = classObj.getName) === null || _a === void 0 ? void 0 : _a.call(classObj)) !== null && _b !== void 0 ? _b : (_c = classObj.model) === null || _c === void 0 ? void 0 : _c.name });
-            return;
+        let key;
+        let kid;
+        let aad;
+        if (scopeId) {
+            const entry = this.scopeWriteKeys.get(scopeId);
+            if (!entry) {
+                // The plugin refuses scope writes before reaching here; this is the
+                // engine's own last line - sealing under the wrong key is never a fallback.
+                throw new Error(`Scope '${scopeId}' holds no read-write key; cannot encrypt.`);
+            }
+            key = entry.cryptoKey;
+            kid = entry.kid;
+            aad = scopeAad(scopeId, entry.kid);
+        }
+        else {
+            key = await this.getCryptoKey();
+            if (!key) {
+                this.logger.warn("Document key is not available; skipping encryption", { className: (_b = (_a = classObj.getName) === null || _a === void 0 ? void 0 : _a.call(classObj)) !== null && _b !== void 0 ? _b : (_c = classObj.model) === null || _c === void 0 ? void 0 : _c.name });
+                return;
+            }
         }
         for (const attribute of encryptableAttributes) {
             const name = attribute.getName();
             if (!(name in document))
                 continue;
-            const encrypted = await this.encryptValue(document[name], key);
+            const encrypted = await this.encryptValue(document[name], key, kid, aad);
             document[name] = encrypted;
         }
     }
@@ -9417,19 +9371,18 @@ class CryptoEngine {
      * @param encryptedKeys - Optional pre-computed list of encrypted field names
      */
     async decryptDocument(document, classObj, encryptedKeys) {
-        var _a, _b, _c;
         if (!this.enabled)
             return;
         const encryptedAttributes = encryptedKeys !== null && encryptedKeys !== void 0 ? encryptedKeys : this.identifyEncryptedKeys(document, classObj);
         if (!encryptedAttributes.length)
             return;
-        const key = await this.getCryptoKey();
-        if (!key) {
-            this.logger.warn("Document key is not available; returning encrypted payload", { className: (_b = (_a = classObj === null || classObj === void 0 ? void 0 : classObj.getName) === null || _a === void 0 ? void 0 : _a.call(classObj)) !== null && _b !== void 0 ? _b : (_c = classObj === null || classObj === void 0 ? void 0 : classObj.model) === null || _c === void 0 ? void 0 : _c.name });
-            return;
-        }
+        // No early bail on a missing legacy key: the keyring dispatches per
+        // payload, and a scope key can open what the document key cannot. A
+        // payload nothing opens stays sealed - which IS the (per-scope) locked
+        // read, handled by the read paths' null convention.
+        const label = document["~scope"];
         for (const name of encryptedAttributes) {
-            const decrypted = await this.decryptValue(document[name], key);
+            const decrypted = await this.decryptValue(document[name], typeof label === "string" ? label : undefined);
             document[name] = decrypted;
         }
     }
@@ -9665,15 +9618,8 @@ const sweepEntry = async (stack, stage, entry, options) => {
     if (isPatch(doc)) {
         throw new TransactionUnsupportedDocError(docId, "patches carry class models and apply through 'applyPatch'.");
     }
-    // A hard delete carries no content to validate; write access is still the
-    // author's to prove - unless this is DocStack's own machinery (an internal
-    // handle: patch application runs before any session exists, and the patch
-    // path's direct writes never pass through policy either - ADR-0044).
+    // A hard delete carries no content to validate.
     if (entry.op === "delete") {
-        const type = doc["~class"];
-        if (typeof type === "string" && !(options === null || options === void 0 ? void 0 : options.skipPolicy)) {
-            await stack.policyEngine.ensureWriteAllowed(type, doc);
-        }
         return;
     }
     if (isRelation(doc)) {
@@ -9704,18 +9650,24 @@ const sweepEntry = async (stack, stage, entry, options) => {
     if (!classObj) {
         throw new TransactionValidationError(`Class '${type}' not found for document '${docId}'.`, docId);
     }
-    // Same refusal the plugin makes (ADR-0018): a locked stack cannot encrypt, and
-    // committing later while still locked would land the fields in the clear.
-    if (classObj.getEncryptedAttributes().length && stack.isLocked()) {
-        throw new StackLockedError(type);
+    // Same refusal the plugin makes (ADR-0018, per scope since ADR-0045): a
+    // sealed key cannot encrypt, and committing later while still sealed would
+    // land the fields in the clear - or under the wrong key, which is worse.
+    if (classObj.getEncryptedAttributes().length) {
+        const label = stack.resolveScopeLabel(doc, classObj.model);
+        if (label) {
+            if (!stack.cryptoEngine.isScopeWritable(label)) {
+                throw new StackLockedError(type, label);
+            }
+        }
+        else if (stack.isLocked()) {
+            throw new StackLockedError(type);
+        }
     }
     const valid = await classObj.validate(doc);
     if (!valid) {
         throw new TransactionValidationError(`Document '${docId}' does not validate against class '${type}'.`, docId);
     }
-    if (!(options === null || options === void 0 ? void 0 : options.skipPolicy)) {
-        await stack.policyEngine.ensureWriteAllowed(type, doc);
-    }
 };
 
 class PouchError extends Error {
@@ -12088,7 +12040,7 @@ class TransactionHandle {
             stagedAt: Date.now(),
         };
         delete entry.doc._rev;
-        await sweepEntry(this.stack, this.stage, entry, { allowClassModels: this.internal, skipPolicy: this.internal });
+        await sweepEntry(this.stack, this.stage, entry, { allowClassModels: this.internal });
         this.stage.set(docId, entry);
         return this.stage.get(docId);
     }
@@ -12415,7 +12367,7 @@ class TransactionEngine {
         //    can be stale (a policy changed, a class tightened). Zero consequences on
         //    refusal.
         for (const entry of entries) {
-            await sweepEntry(this.stack, stage, entry, { allowClassModels: handle.internal, skipPolicy: handle.internal });
+            await sweepEntry(this.stack, stage, entry, { allowClassModels: handle.internal });
         }
         // 2. Rev pre-flight: every staged id's stored winner must still be the
         //    revision it was staged against. `allDocs` is below the plugin - revs
@@ -12643,6 +12595,7 @@ const DOCSTACK_OPTION_KEYS = [
     "disableCryptoEngine",
     "documentKey",
     "transactions",
+    "accessKeys",
     "logLevel",
 ];
 /**
@@ -12792,6 +12745,19 @@ class ClientStack extends Stack {
          */
         this.classDocSubscribers = new Map();
         this.modelWorker = null;
+        /**
+         * Engine for enforcing read/write access control policies.
+         * Policies are evaluated based on user session and document content.
+         */
+        /**
+         * The access-scope registry: every `~AccessScope` document, grouped by
+         * `scopeId` (ADR-0045). Built from the database, independent of which CEKs
+         * the keyring actually holds - the registry knows a scope's key ids even
+         * when the session cannot open them, which is what the label↔kid mismatch
+         * guard needs (spec 02 §2.3 rule 2).
+         */
+        this.accessScopeRegistry = null;
+        this.accessScopeRegistryDirty = true;
         /**
          * Application patches held back because they write encrypted attributes and the stack
          * has no key yet. Replayed by {@link unlock}. Kept in memory on purpose - reopening
@@ -12956,10 +12922,12 @@ class ClientStack extends Stack {
                     throw new Error(`exportContent - no such content class: ${unknown.join(", ")}`);
                 }
             }
-            // A locked stack reads encrypted attributes back as `null`. Writing that into an
-            // export would lose data in a way nothing downstream could detect, so it is
-            // refused unless the caller has said they want the rest anyway.
-            if (this.isLocked() && !options.allowLossyWhenLocked) {
+            // A sealed payload reads back as `null` - a locked legacy key, or a
+            // scope the keyring cannot open. Writing that into an export would lose
+            // data in a way nothing downstream could detect, so it is refused
+            // unless the caller has said they want the rest anyway, naming what is
+            // sealed (spec 02 §5: lossy per locked scope, and the report says which).
+            if (!options.allowLossyWhenLocked) {
                 const encrypted = [];
                 for (const className of classes) {
                     const classObj = await this.getClassSnapshot(className);
@@ -12967,9 +12935,17 @@ class ClientStack extends Stack {
                         encrypted.push(className);
                 }
                 if (encrypted.length) {
-                    throw new Error(`exportContent - the stack is locked, so encrypted attributes on ${encrypted.join(", ")} ` +
-                        "would be exported as null. Unlock it with 'stack.unlock(documentKey)', or pass " +
-                        "'allowLossyWhenLocked: true' to accept the loss.");
+                    const sealedScopes = this.cryptoEngine.isEnabled() ? await this.lockedScopeIds() : [];
+                    if (this.isLocked()) {
+                        throw new Error(`exportContent - the stack is locked, so encrypted attributes on ${encrypted.join(", ")} ` +
+                            "would be exported as null. Unlock it with 'stack.unlock(documentKey)', or pass " +
+                            "'allowLossyWhenLocked: true' to accept the loss.");
+                    }
+                    if (sealedScopes.length) {
+                        throw new Error(`exportContent - scopes ${sealedScopes.join(", ")} are sealed, so their encrypted attributes ` +
+                            "would be exported as null. Unlock them with 'stack.unlockScopes(attributeKey)', or pass " +
+                            "'allowLossyWhenLocked: true' to accept the loss.");
+                    }
                 }
             }
             const keep = (doc) => options.includeInactive || doc.active !== false;
@@ -13563,41 +13539,48 @@ class ClientStack extends Stack {
          * @param docs - The documents just written; omit to invalidate everything.
          */
         this.invalidateWriteCaches = (docs) => {
-            var _a;
             let classTouched = !docs;
-            let policyTouched = !docs;
+            let scopeTouched = !docs;
             for (const doc of docs !== null && docs !== void 0 ? docs : []) {
                 if (!doc || typeof doc !== "object")
                     continue;
                 if (isClassModel(doc))
                     classTouched = true;
-                else if (doc["~class"] === "~Policy")
-                    policyTouched = true;
-                if (classTouched && policyTouched)
+                else if (doc["~class"] === "~AccessScope")
+                    scopeTouched = true;
+                if (classTouched && scopeTouched)
                     break;
             }
             if (classTouched) {
                 this.classModelCache.clear();
                 this.classSnapshotCache.clear();
             }
-            if (policyTouched) {
-                (_a = this.policyEngine) === null || _a === void 0 ? void 0 : _a.invalidatePolicyCache();
+            if (scopeTouched) {
+                this.accessScopeRegistryDirty = true;
             }
         };
         /**
          * Whether a database-level `limit` returns the same rows as limiting in memory.
          *
-         * `findDocuments` filters per document *after* the query - policy checks drop
-         * unreadable documents, and a locked crypto engine drops documents whose visible
-         * fields are all encrypted. A limit applied before either would under-fill. The
-         * query engine asks this before pushing a SQL LIMIT into the fetch.
+         * `findDocuments` drops a document whose visible fields are all sealed - a
+         * locked legacy key, or a scope the keyring cannot open. A limit applied
+         * before that filter would under-fill. So pushdown is allowed exactly when
+         * no row of this class can drop: the class has no encrypted attributes, or
+         * every key that might seal one is held (the legacy key, and every declared
+         * scope - a document may carry any label). The query engine asks this
+         * before pushing a SQL LIMIT into the fetch.
          *
          * @param className - The class being queried.
          */
         this.canApplyQueryLimitEarly = async (className) => {
-            if (this.cryptoEngine.isEnabled() && !this.cryptoEngine.getDocumentKey())
+            if (!this.cryptoEngine.isEnabled())
+                return true;
+            const classObj = await this.getClassSnapshot(className).catch(() => null);
+            if (!classObj || !classObj.getEncryptedAttributes().length)
+                return true;
+            if (!this.cryptoEngine.getDocumentKey())
                 return false;
-            return !(await this.policyEngine.hasPoliciesFor(className));
+            return (await this.lockedScopeIds()).length === 0;
         };
         /** Fields whose sort index exists this session; avoids re-running createIndex. */
         this.sortIndexSession = new Map();
@@ -14268,7 +14251,6 @@ class ClientStack extends Stack {
                 // A name-derived id converges: the two writes are the same document.
                 const result = await this.createDoc(classModel.name, classOrigin.getName(), classOrigin, classModel);
                 fnLogger.info("Added class card", { result });
-                await this.ensureDefaultPolicyForClass(result);
                 return result;
             }
             catch (e) {
@@ -14448,7 +14430,6 @@ class ClientStack extends Stack {
                     // console.log("Doc after merge", { doc_ })
                 }
                 fnLogger.info("Doc AFTER elaboration (i.e. merge)", { doc_ });
-                await this.policyEngine.ensureWriteAllowed(type, doc_);
                 let response = await db.put(doc_);
                 // Stamped from the response, not left as the pre-put draft. A caller cannot
                 // otherwise tell a document that landed from one that did not - which is
@@ -14552,7 +14533,6 @@ class ClientStack extends Stack {
                     fnLogger.info("Doc BEFORE elaboration (i.e. merge)", { doc, params });
                     const doc_ = withoutEmptyRev(Object.assign(Object.assign(Object.assign({}, doc), params), { _id: docId, _rev: doc._rev, "~updateTimestamp": new Date().getTime() }));
                     fnLogger.info("Doc AFTER elaboration (i.e. merge)", { doc_ });
-                    await this.policyEngine.ensureWriteAllowed(type, doc_);
                     documents.push(doc_);
                     if (isNewDoc)
                         newDocsIds.push(docId);
@@ -14777,8 +14757,6 @@ class ClientStack extends Stack {
             const doc = await this.db.get(_id);
             if (doc) {
                 try {
-                    const targetClass = doc["~class"];
-                    await this.policyEngine.ensureWriteAllowed(targetClass, doc);
                     await this.db.put(Object.assign(Object.assign({}, doc), { active: false }));
                     return true;
                 }
@@ -14921,7 +14899,6 @@ class ClientStack extends Stack {
         };
         this.jobEngine = new JobEngine(this);
         this.jobScheduler = new JobScheduler(this);
-        this.policyEngine = new PolicyEngine(this);
         this.cryptoEngine = new CryptoEngine(this);
         // Re-created, never carried over: `reset()` re-runs initialize, and a stage
         // surviving a reset would resurrect uncommitted writes (ADR-0039).
@@ -15076,6 +15053,9 @@ class ClientStack extends Stack {
     clearAuthSession() {
         this.authSession = undefined;
         this.cryptoEngine.setDocumentKey(null);
+        // Scope CEKs are session material too: what the attribute key opened
+        // closes with it. Re-adoption goes through `unlockScopes`.
+        this.cryptoEngine.dropScopeKeys();
     }
     /**
      * Whether the stack is operating without its document encryption key.
@@ -15141,6 +15121,153 @@ class ClientStack extends Stack {
         this.dispatchEvent(new CustomEvent("unlocked", { detail: { stackName: this.name } }));
         return this;
     }
+    /**
+     * The access-scope registry, loaded from `~AccessScope` documents and
+     * refreshed whenever one is written (ADR-0045). Raw read: scope docs are
+     * the machinery that DECIDES readability - they cannot sit behind it.
+     */
+    async getAccessScopeRegistry() {
+        if (!this.accessScopeRegistry || this.accessScopeRegistryDirty) {
+            const registry = new Map();
+            const found = await this.db.find({
+                selector: { "~class": "~AccessScope", active: true },
+                limit: 2 ** 31 - 1,
+            }).catch(() => ({ docs: [] }));
+            for (const raw of found.docs) {
+                if (typeof raw.scopeId !== "string" || typeof raw.kid !== "string")
+                    continue;
+                let entry = registry.get(raw.scopeId);
+                if (!entry) {
+                    entry = { scopeId: raw.scopeId, kids: new Set(), winningVersion: -Infinity, docs: [] };
+                    registry.set(raw.scopeId, entry);
+                }
+                entry.kids.add(raw.kid);
+                entry.docs.push(raw);
+                if (typeof raw.version === "number" && raw.version > entry.winningVersion)
+                    entry.winningVersion = raw.version;
+            }
+            this.accessScopeRegistry = registry;
+            this.accessScopeRegistryDirty = false;
+        }
+        return this.accessScopeRegistry;
+    }
+    /**
+     * The scope a document's write seals under: its own `~scope` label, else
+     * its class's `defaultScope` (spec 02 §2.2 - the document's value wins).
+     */
+    resolveScopeLabel(doc, classModel) {
+        const own = doc === null || doc === void 0 ? void 0 : doc["~scope"];
+        if (typeof own === "string" && own)
+            return own;
+        const fallback = classModel === null || classModel === void 0 ? void 0 : classModel.defaultScope;
+        return typeof fallback === "string" && fallback ? fallback : undefined;
+    }
+    /** Every key id belonging to a scope, across rotation versions - or null for an unknown scope. */
+    async getAccessScopeKids(scopeId) {
+        var _a, _b;
+        const registry = await this.getAccessScopeRegistry();
+        return (_b = (_a = registry.get(scopeId)) === null || _a === void 0 ? void 0 : _a.kids) !== null && _b !== void 0 ? _b : null;
+    }
+    /** Whether a declared scope's CEK is absent from the keyring - its content is sealed. */
+    isScopeLocked(scopeId) {
+        return !this.cryptoEngine.isScopeWritable(scopeId);
+    }
+    /** Declared scopes whose CEK the keyring lacks. Loaded scopes only - call after open. */
+    async lockedScopeIds() {
+        const registry = await this.getAccessScopeRegistry();
+        return [...registry.keys()].filter(scopeId => !this.cryptoEngine.isScopeWritable(scopeId));
+    }
+    /**
+     * Attempts every declared access scope with the session's attribute key
+     * (ADR-0045): the ABE decryption either yields a scope's CEK - verified
+     * against the scope's canary, then admitted to the keyring - or fails,
+     * and the scope stays locked. There is no gate to ask; this IS the access
+     * decision. Idempotent: a later call with better material unlocks more.
+     * Deferred patches that were waiting on a scope replay after.
+     */
+    async unlockScopes(attributeKey) {
+        if (!this.cryptoEngine.isEnabled()) {
+            throw new Error("Stack was opened with the crypto engine disabled; there are no scopes to unlock.");
+        }
+        if (!attributeKey)
+            throw new Error("unlockScopes requires the session's attribute key.");
+        const fnLogger = logger.child({ method: "unlockScopes" });
+        this.accessScopeRegistryDirty = true;
+        const registry = await this.getAccessScopeRegistry();
+        if (!registry.size)
+            return { unlocked: [], locked: [] };
+        const { decryptCek } = await import('./index2.js');
+        const unlocked = [];
+        const locked = [];
+        for (const entry of registry.values()) {
+            let opened = false;
+            for (const scopeDoc of entry.docs) {
+                if (this.cryptoEngine.getReadableKeyIds().includes(scopeDoc.kid)) {
+                    opened = true;
+                    continue;
+                }
+                const cekBytes = await decryptCek(attributeKey, scopeDoc.abeWrappedCek).catch(() => null);
+                if (!cekBytes)
+                    continue;
+                const cekHex = Array.from(cekBytes, (b) => b.toString(16).padStart(2, "0")).join("");
+                // The scope doc's stated kid and canary are both admission tests: a
+                // corrupted or tampered scope doc is an error here, not garbage later.
+                if (await deriveKeyId(cekHex) !== scopeDoc.kid) {
+                    fnLogger.warn("Scope CEK does not match the scope document's kid; refusing admission", { scopeId: entry.scopeId, version: scopeDoc.version });
+                    continue;
+                }
+                if (!(await this.cryptoEngine.verifyScopeCek(entry.scopeId, cekHex, scopeDoc.encryptedMarker))) {
+                    fnLogger.warn("Scope CEK does not verify against the scope's canary; refusing admission", { scopeId: entry.scopeId, version: scopeDoc.version });
+                    continue;
+                }
+                const mode = scopeDoc.version === entry.winningVersion ? "read-write" : "read-only";
+                await this.cryptoEngine.admitScopeKey(entry.scopeId, cekHex, scopeDoc.version, mode);
+                opened = true;
+                this.dispatchEvent(new CustomEvent("scopeUnlocked", { detail: { stackName: this.name, scopeId: entry.scopeId, version: scopeDoc.version, mode } }));
+            }
+            (opened ? unlocked : locked).push(entry.scopeId);
+        }
+        if (unlocked.length && this.deferredPatches.length) {
+            // A patch held back by a sealed scope replays now - the per-scope
+            // half of the ADR-0018/0040 deferral discipline.
+            const deferred = this.deferredPatches;
+            this.deferredPatches = [];
+            await this.applyConsumerPatches(deferred);
+        }
+        fnLogger.info("Scope unlock attempted", { unlocked, locked });
+        return { unlocked, locked };
+    }
+    /**
+     * AUTHORITY-side helper: assembles a complete `~AccessScope` document from
+     * a fresh (or supplied) CEK - ABE-sealing it under the policy, stamping the
+     * kid, minting the per-scope canary. Runs wherever the application controls
+     * (its server, an admin ceremony, tests); it needs the authority PUBLIC key
+     * only, never the master secret. The document is returned, not written -
+     * publishing it (and distributing attribute keys) is the consumer's act.
+     */
+    static async buildAccessScope(input) {
+        var _a, _b;
+        const { wrapCek, normalizePolicy } = await import('./index2.js');
+        const cekHex = (_a = input.cekHex) !== null && _a !== void 0 ? _a : Array.from(crypto.getRandomValues(new Uint8Array(32)), (b) => b.toString(16).padStart(2, "0")).join("");
+        if (!/^[0-9a-f]{64}$/.test(cekHex))
+            throw new Error("buildAccessScope needs a 32-byte hex CEK.");
+        const cekBytes = new Uint8Array(cekHex.match(/.{2}/g).map(h => parseInt(h, 16)));
+        const kid = await deriveKeyId(cekHex);
+        const key = await importAesKeyFromHex(cekHex);
+        const marker = await encryptWithAesGcm(JSON.stringify({ nonce: Array.from(crypto.getRandomValues(new Uint8Array(12)), (b) => b.toString(16).padStart(2, "0")).join("") }), key, kid, scopeAad(input.scopeId, kid));
+        const version = (_b = input.version) !== null && _b !== void 0 ? _b : 1;
+        return {
+            _id: `~scope-${input.scopeId}-v${version}`,
+            "~class": "~AccessScope",
+            active: true,
+            scopeId: input.scopeId,
+            policyString: normalizePolicy(input.policyString),
+            abeWrappedCek: await wrapCek(input.pk, input.policyString, cekBytes),
+            kid,
+            version,
+            encryptedMarker: marker,
+        };
+    }
     /**
      * Encrypts bootstrap documents that were seeded before this stack had a key.
      *
@@ -15209,31 +15336,6 @@ class ClientStack extends Stack {
             return 0;
         }
     }
-    async ensureDefaultPolicyForClass(targetClass) {
-        const fnLogger = logger.child({ method: "ensureDefaultPolicyForClass", targetClass: targetClass._id });
-        const existingPolicy = await this.findDocument({
-            "~class": { $eq: "~Policy" },
-            targetClass: { $elemMatch: { $eq: targetClass._id } }
-        });
-        if (existingPolicy) {
-            return;
-        }
-        const policyDoc = {
-            _id: `Policy-${targetClass._id}`,
-            "~class": "~Policy",
-            active: true,
-            rule: "return session && session.sessionStatus === 'active';",
-            description: `Default policy for ${targetClass.name || targetClass._id}`,
-            targetClass: [targetClass._id],
-        };
-        fnLogger.info("Creating default policy", { policyDoc });
-        try {
-            await this.db.bulkDocs([policyDoc]);
-        }
-        catch (error) {
-            throw new Error(`Failed to create default policy for ${targetClass._id}: ${(error === null || error === void 0 ? void 0 : error.message) || error}`);
-        }
-    }
     /**
      * Creates and initializes a new ClientStack instance.
      * This is the primary way to instantiate a stack - the constructor is private.
@@ -15276,6 +15378,23 @@ class ClientStack extends Stack {
                 && existing.target === p.target
                 && existing.active !== false)));
         }
+        // Scope material is attempted AFTER patches: a consumer patch may carry
+        // the very `~AccessScope` docs the key opens, and a patch deferred on a
+        // sealed scope replays inside `unlockScopes`. Adoption discipline is the
+        // consumer's (spec 02 §4): the stack stores nothing of the key.
+        if ((options === null || options === void 0 ? void 0 : options.accessKeys) && stack.cryptoEngine.isEnabled()) {
+            let { attributeKey } = options.accessKeys;
+            if (attributeKey) {
+                await stack.unlockScopes(attributeKey);
+            }
+            const stillLocked = await stack.lockedScopeIds();
+            if (stillLocked.length && options.accessKeys.requestAttributeKey) {
+                const fetched = await options.accessKeys.requestAttributeKey(stillLocked).catch(() => null);
+                if (fetched) {
+                    await stack.unlockScopes(fetched);
+                }
+            }
+        }
         if (options === null || options === void 0 ? void 0 : options.credentials) {
             await stack.authenticate(options.credentials);
         }
@@ -15542,7 +15661,7 @@ class ClientStack extends Stack {
         try {
             for (let index = 0; index < patches.length; index++) {
                 const patch = patches[index];
-                if (this.isLocked() && await this.patchNeedsDocumentKey(patch, stagedClassSchema)) {
+                if (await this.patchBlockedByLock(patch, stagedClassSchema)) {
                     await deferFrom(index);
                     break;
                 }
@@ -15724,6 +15843,47 @@ class ClientStack extends Stack {
      * have when patch N had committed.
      * @returns `true` if any document in it belongs to a class with encrypted attributes.
      */
+    /**
+     * The deferral barrier, generalized per scope (spec 02 §5): a patch is
+     * blocked when the legacy half applies (stack locked and the patch needs
+     * the document key) OR any document it carries writes into a declared
+     * scope whose CEK the keyring lacks - sealing under the wrong key is never
+     * a fallback, so the patch waits for `unlockScopes` exactly as key-needing
+     * patches wait for `unlock`.
+     */
+    async patchBlockedByLock(patch, stagedSchema) {
+        var _a, _b, _c, _d, _e;
+        if (this.isLocked() && await this.patchNeedsDocumentKey(patch, stagedSchema))
+            return true;
+        if (!this.cryptoEngine.isEnabled())
+            return false;
+        const hasEncrypted = (schema) => !!schema && Object.values(schema).some((attribute) => { var _a; return ((_a = attribute === null || attribute === void 0 ? void 0 : attribute.config) === null || _a === void 0 ? void 0 : _a.encrypted) === true; });
+        const classModelsInPatch = new Map();
+        for (const doc of (_a = patch.docs) !== null && _a !== void 0 ? _a : []) {
+            if (isClassModel(doc))
+                classModelsInPatch.set((_b = doc.name) !== null && _b !== void 0 ? _b : doc._id, doc);
+        }
+        for (const doc of (_c = patch.docs) !== null && _c !== void 0 ? _c : []) {
+            if (isClassModel(doc) || isRelation(doc))
+                continue;
+            const className = doc["~class"];
+            if (typeof className !== "string" || !className)
+                continue;
+            const inPatch = classModelsInPatch.get(className);
+            const stored = inPatch ? null : await this.getClassModel(className).catch(() => null);
+            const label = this.resolveScopeLabel(doc, (inPatch !== null && inPatch !== void 0 ? inPatch : stored));
+            if (!label)
+                continue;
+            const schema = (_e = (_d = inPatch === null || inPatch === void 0 ? void 0 : inPatch.schema) !== null && _d !== void 0 ? _d : stagedSchema === null || stagedSchema === void 0 ? void 0 : stagedSchema(className)) !== null && _e !== void 0 ? _e : stored === null || stored === void 0 ? void 0 : stored.schema;
+            if (hasEncrypted(schema) && !this.cryptoEngine.isScopeWritable(label)) {
+                // Only a DECLARED scope defers - an unknown label is a patch
+                // fault the chain should refuse loudly, not wait on forever.
+                if ((await this.getAccessScopeRegistry()).has(label))
+                    return true;
+            }
+        }
+        return false;
+    }
     async patchNeedsDocumentKey(patch, stagedSchema) {
         var _a;
         // A one-shot job's touch-set cannot be inspected, so the author answers the
@@ -16347,11 +16507,6 @@ class ClientStack extends Stack {
             return classesInResult.get(className);
         };
         for (const doc of docs) {
-            const canRead = await this.policyEngine.isReadableDocument(doc);
-            if (!canRead) {
-                logger.info("processFoundDocuments - document is not readable by policy", { docId: doc._id, docClass: doc["~class"] });
-                continue;
-            }
             const encryptedKeys = this.cryptoEngine.identifyEncryptedKeys(doc);
             const classObj = encryptedKeys.length || (fields && fields.length)
                 ? await classFor(doc["~class"])
@@ -16372,14 +16527,18 @@ class ClientStack extends Stack {
             return doc;
         }
         const clone = Object.assign({}, doc);
-        const hasDocumentKey = Boolean(this.cryptoEngine.getDocumentKey());
-        if (hasDocumentKey && encryptedKeys.length) {
+        // Per payload, not per stack (spec 02 §5): the keyring opens what it
+        // can - legacy key, retired keys, unlocked scope CEKs - and whatever
+        // stays sealed (a locked scope, a missing legacy key, a payload whose
+        // label fails its AAD) reads as `null`, the locked-read convention
+        // applied at the granularity the keyring actually has.
+        let sealedCount = 0;
+        if (encryptedKeys.length) {
             await this.cryptoEngine.decryptDocument(clone, classObj, encryptedKeys);
-        }
-        else if (encryptedKeys.length) {
             for (const key of encryptedKeys) {
-                if (clone[key] !== undefined) {
+                if (isEncryptedPayload(clone[key])) {
                     clone[key] = null;
+                    sealedCount++;
                 }
             }
         }
@@ -16393,7 +16552,9 @@ class ClientStack extends Stack {
             }
             return clone[key] !== undefined;
         });
-        if (!hasDocumentKey && encryptedKeySet.size) {
+        if (sealedCount > 0) {
+            // A document whose every visible field stayed sealed is hidden -
+            // there is nothing of it this keyring can show.
             const nonEncryptedVisible = visibleKeys.filter((key) => !encryptedKeySet.has(key));
             if (!nonEncryptedVisible.length) {
                 return null;
@@ -17331,4 +17492,4 @@ class DocStack extends EventTarget {
     }
 }
 
-export { Attribute, CONTENT_EXPORT_FORMAT, Class, ClientStack, DATA_MODEL_CLASSES, DocStack, DocStackSyncHandle, Domain, INTERNAL_DOC_CLASSES, INTERNAL_DOC_IDS, INTERNAL_DOC_ID_PREFIXES, JOB_SCHEDULE_DOC_ID, JobEngine, JobScheduler, META_CLASSES, OPTIONAL_INTERNAL_DOC_CLASSES, SYNC_META_DOC_ID, SYSTEM_SEEDED_DOC_IDS, StackLockedError, StackSyncHandle, StackWriteGuardError, SyncSchemaMismatchError, TransactionConflictError, TransactionDb, TransactionEngine, TransactionHandle, TransactionStateError, TransactionUnsupportedDocError, TransactionValidationError, TransactionsDisabledError, Trigger, classTenants, collectQueryClasses, createClassFilter, createReplicationFilter, DocStack as default, deriveKeyId, deriveTenantScope, describeFilter, hasClassRules, isContentClassName, isContentDocument, isContentRelation, isEncryptedPayload, isInternalDoc, nextOccurrence, parseSchedule, publishSchemaVersion, readRemoteConsumerSchemaVersion, readRemoteSchemaVersion, resolveInternalClasses, withFilterIdentity };
+export { Attribute, CONTENT_EXPORT_FORMAT, Class, ClientStack, DATA_MODEL_CLASSES, DocStack, DocStackSyncHandle, Domain, INTERNAL_DOC_CLASSES, INTERNAL_DOC_IDS, INTERNAL_DOC_ID_PREFIXES, JOB_SCHEDULE_DOC_ID, JobEngine, JobScheduler, META_CLASSES, OPTIONAL_INTERNAL_DOC_CLASSES, SYNC_META_DOC_ID, SYSTEM_SEEDED_DOC_IDS, StackLockedError, StackScopeMismatchError, StackSyncHandle, StackWriteGuardError, SyncSchemaMismatchError, TransactionConflictError, TransactionDb, TransactionEngine, TransactionHandle, TransactionStateError, TransactionUnsupportedDocError, TransactionValidationError, TransactionsDisabledError, Trigger, classTenants, collectQueryClasses, createClassFilter, createReplicationFilter, DocStack as default, deriveKeyId, deriveTenantScope, describeFilter, hasClassRules, isContentClassName, isContentDocument, isContentRelation, isEncryptedPayload, isInternalDoc, nextOccurrence, parseSchedule, publishSchemaVersion, readRemoteConsumerSchemaVersion, readRemoteSchemaVersion, resolveInternalClasses, withFilterIdentity };