@docstack/client 0.2.0 → 0.3.0

package/lib/plugins/pouchdb.d.ts

@@ -18,7 +18,22 @@ export declare class StackLockedError extends Error {
     name: string;
     /** The class the refused document belongs to. */
     readonly className: string;
-    constructor(className: string);
+    /** The sealed scope, when the refusal is a scope's rather than the legacy key's (ADR-0045). */
+    readonly scopeId?: string;
+    constructor(className: string, scopeId?: string);
+}
+/**
+ * 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.
+ */
+export declare class StackScopeMismatchError extends Error {
+    name: string;
+    readonly docId: string;
+    readonly scopeId: string;
+    constructor(docId: string, scopeId: string, kid: string | undefined);
 }
 /**
  * Resolves the effective `new_edits` flag for a `bulkDocs` call.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docstack/client",
   "description": "One does not simply stack documents.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "main": "lib/index.js",
   "module": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -44,6 +44,7 @@
   },
   "homepage": "https://onyx.ac/docstack",
   "dependencies": {
+    "@docstack/abe": "^0.1.0",
     "@docstack/shared": "^0.1.0",
     "jsondiffpatch": "^0.7.3",
     "pouchdb-selector-core": "^9.0.0",

package/lib/core/policy-engine/index.d.ts

@@ -1,132 +0,0 @@
-import type ClientStack from "../stack.js";
-import type { Document } from "@docstack/shared";
-/** The type of operation being authorized: read or write. */
-export type PolicyOperation = "read" | "write";
-/**
- * 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;'
- * });
- * ```
- */
-export declare class PolicyEngine {
-    /** Reference to the parent stack for database and session access. */
-    private readonly 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.
-     */
-    private allPoliciesCache;
-    /**
-     * 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.
-     */
-    private compiledRules;
-    /**
-     * Creates a new PolicyEngine instance.
-     * @param stack - The parent ClientStack instance
-     */
-    constructor(stack: ClientStack);
-    /**
-     * 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(): void;
-    /**
-     * Gets the current authentication session proof.
-     * @returns The session proof, or undefined if not authenticated
-     */
-    private getSessionProof;
-    /**
-     * 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
-     */
-    private shouldBypass;
-    private loadPolicies;
-    private getTargetIdentifiers;
-    private resolveClassTarget;
-    /**
-     * 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
-     */
-    private evaluateRule;
-    private filterPoliciesForSession;
-    private authorize;
-    /**
-     * 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.
-     */
-    hasPoliciesFor(targetClass: string): Promise<boolean>;
-    /**
-     * 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);
-     * ```
-     */
-    ensureWriteAllowed(targetClass: string, document: Document | null): Promise<void>;
-    /**
-     * 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);
-     * }
-     * ```
-     */
-    isReadableDocument(document: Document): Promise<boolean>;
-}