@embedpdf/engine-core 3.0.0-next.13 → 3.0.0-next.15

package/dist/{DocumentSecurityService-_JRjqvoI.d.ts → DocumentSecurityService-CU1M6Q7m.d.ts}

@@ -1,77 +1,16 @@
-import { Su as PdfBits, gu as IdentityClaims, hl as CollabTarget, hu as DocCapability } from "./AnnotationListSnapshot-D3mFut1e.js";
-//#region src/promise/AbortablePromise.d.ts
-type AbortableExecutor<T, P> = (resolve: (value: T | PromiseLike<T>) => void, reject: (reason: unknown) => void, progress: (p: P) => void, signal: AbortSignal) => void;
-/**
- * Awaitable Promise subclass with abort and progress.
- *
- * Symbol.species returns plain Promise so chained .then/.catch/.finally
- * return regular promises and never try to synthesize a new
- * AbortablePromise (which would have no executor).
- *
- * Settlement contract:
- *   - The first settlement wins. resolve/reject handed to the executor
- *     are wrapped so that any subsequent call (whether by the executor,
- *     by abort(), or by both racing) becomes a silent no-op.
- *   - abort() rejects the public promise with AbortError immediately,
- *     even if the executor never observes the AbortSignal. The executor
- *     still receives the AbortSignal so it can stop real work
- *     cooperatively (release a queue slot, abort fetch, post a worker
- *     abort, etc.). Anything the executor does after that — including
- *     a late resolve(value), a late reject(error), or a rejected inner
- *     Promise inside AbortablePromise.run — is dropped silently.
- *   - abort() after settlement is a no-op.
- */
-declare class AbortablePromise<T, P = never> extends Promise<T> {
-  static get [Symbol.species](): PromiseConstructor;
-  readonly signal: AbortSignal;
-  private readonly _ctrl;
-  private readonly _progressCbs;
-  private readonly _state;
-  private readonly _internalReject;
-  constructor(executor: AbortableExecutor<T, P>);
-  /**
-   * Abort the underlying operation.
-   *
-   * - If the promise has already settled, this is a no-op.
-   * - Otherwise the public promise rejects synchronously with an
-   *   AbortError (wrapping the supplied reason if it is not already an
-   *   AbortError) and the AbortSignal fires for any cooperative
-   *   cancellation the executor wired up.
-   */
-  abort(reason?: unknown): void;
-  /**
-   * Subscribe to progress events. Returns an unsubscribe function.
-   */
-  onProgress(cb: (p: P) => void): () => void;
-  /**
-   * Wrap a value in an already-resolved AbortablePromise. Mirrors Promise.resolve.
-   */
-  static resolveValue<T>(value: T | PromiseLike<T>): AbortablePromise<T>;
-  /**
-   * Wrap a thrown reason in an already-rejected AbortablePromise.
-   */
-  static rejectReason<T = never>(reason: unknown): AbortablePromise<T>;
-  /**
-   * Run an async function as an AbortablePromise so callers get .abort() and .signal.
-   * The async function receives the AbortSignal (and a progress emitter) so it can
-   * cooperate with the abort.
-   *
-   * If abort() fires while the inner async function is still running, the
-   * public promise rejects with AbortError immediately. The inner async
-   * function's eventual settlement (resolve or reject) is funneled through
-   * the wrapped settlers and silently dropped — including a late rejection
-   * from the underlying work, which prevents an UnhandledRejection because
-   * the .then(resolve, reject) below "handles" it via the no-op.
-   */
-  static run<T, P = never>(fn: (signal: AbortSignal, progress: (p: P) => void) => Promise<T>): AbortablePromise<T, P>;
-}
-//#endregion
+import { C_ as DocCapability, Du as BundleLimits, E_ as Identity, M_ as PdfBits, P_ as AbortablePromise, Wh as DocumentProtection, Xd as EditSessionAccess, ph as FieldRights } from "./AnnotationList-CkijRHet.js";
 //#region src/engine/passwordPrompt.d.ts
 type PasswordPrompt = {
   readonly state: 'none';
 } | {
   readonly state: 'required';
   readonly hint: 'user' | 'owner' | null;
+  /**
+   * The last password tried (at `open()` or `unlock()`) was wrong, so a
+   * prompt can say so. A wrong password opens the document locked, as no
+   * password does: one path for "this file needs a password".
+   */
+  readonly incorrect: boolean;
 } | {
   readonly state: 'optional';
   readonly hint: 'owner';
@@ -80,7 +19,7 @@ type PasswordPrompt = {
  * Derive the high-level password prompt from the raw security state.
  *
  * The function is pure and total — every `DocumentSecurityState`
- * maps to exactly one `PasswordPrompt`. Use this as the SINGLE source
+ * maps to exactly one `PasswordPrompt`. Use this as the single source
  * of truth wherever the SDK exposes a "do you need a password?" flag:
  * both `LocalDocumentSecurityService` and `CloudDocumentSecurityService`
  * call it, so the contract can never drift.
@@ -110,7 +49,7 @@ type PasswordPrompt = {
  *
  *   6. fallthrough → { state: 'none' }   open and nothing more available
  */
-declare function passwordPromptFromState(state: DocumentSecurityState): PasswordPrompt;
+declare function passwordPromptFromState(state: DocumentSecurityState, incorrect?: boolean): PasswordPrompt;
 //#endregion
 //#region src/engine/DocumentSecurityService.d.ts
 type DocumentOpenMode = 'none' | 'user' | 'owner';
@@ -123,10 +62,9 @@ type DocumentAccessReason = 'password' | 'cdn' | 'permissions-unknown';
  * not the raw bit names — so docs can render "Print: disabled" without
  * the reader needing to know PDF bit positions.
  *
- * Computed from {@link PdfBits} via the strict ISO 32000 rules:
- *   bit 12 only meaningful when bit 3 is also set
- *   form modification requires both bit 6 AND bit 4
- *   form fill is satisfied by bit 6 OR bit 9
+ * Computed from {@link PdfBits} as `pdf.permissions` reads them, which
+ * is what Acrobat allows on the file: for example, form fill comes with
+ * bit 4, 6 or 9, and form modification needs both bit 4 and bit 6.
  */
 interface PdfPermissionAdvisory {
   readonly canPrint: boolean;
@@ -240,12 +178,13 @@ interface DocumentAccessInfo {
    * Sorted alphabetically for stable display.
    */
   readonly effectiveScope: string[];
-  readonly identity: {
-    readonly user_id?: string;
-    readonly group_id?: string;
-    readonly groups?: string[];
-    readonly display_name?: string;
-  };
+  /**
+   * What the document's signatures forbid (`null` when it has none): a
+   * certification or a signed lock takes capabilities away from every
+   * caller, and `effectiveScope` already leaves them out.
+   */
+  readonly protection: DocumentProtection | null;
+  readonly identity: Identity;
   readonly originPasswordPolicy: {
     readonly mode: 'not-needed' | 'client-retry' | 'server-session';
   };
@@ -255,7 +194,7 @@ interface DocumentAccessInfo {
    * `viewport.width` points whose renders are durable, CDN-shared
    * artifacts, plus the reserved tile-pyramid block. Local engines report
    * nothing here (continuous rendering); cloud engines surface it so
-   * `snapFullPageViewport` can conform requests EXPLICITLY — the SDK
+   * `snapFullPageViewport` can conform requests explicitly — the SDK
    * never snaps implicitly (engine parity).
    */
   readonly renderPolicy?: {
@@ -274,6 +213,17 @@ interface DocumentAccessInfo {
     readonly background: 'white';
     readonly enforced: boolean;
   };
+  /**
+   * The deployment's limits for an annotation import: the cloud client
+   * checks a bundle against these before its bytes move.
+   */
+  readonly bundleLimits: BundleLimits;
+  /**
+   * The caller's editing session and the object numbers handed to it,
+   * present when the caller may create objects and named its session
+   * (`X-Engine-Session-Id`).
+   */
+  readonly edit?: EditSessionAccess;
 }
 interface DocumentUnlockInput {
   readonly password: string;
@@ -283,56 +233,65 @@ interface DocumentUnlockResult {
   readonly security: DocumentSecurityState;
   readonly access?: DocumentAccessInfo;
 }
+/**
+ * What an annotation is and whose: what `allowsAnnotation('update' |
+ * 'delete', …)` reads. An `Annotation` is one; so is `{ userId, groupId }`.
+ * A widget (`subtype: 'widget'`) belongs to a form field: changing or
+ * deleting one takes `doc.forms.modify`, whoever's it is.
+ */
+interface AnnotationOwner {
+  subtype?: string;
+  userId?: string | null;
+  groupId?: string | null;
+}
 interface DocumentSecurityService {
   /**
    * Raw structured security probe. Stable across engines, refreshed
-   * after unlock/refresh. Power users and diagnostic tools read this;
-   * most dev code uses the higher-level accessors below.
+   * after an unlock. Power users and diagnostic tools read this; most
+   * code uses the higher-level accessors below.
    */
-  readonly current: DocumentSecurityState;
+  readonly state: DocumentSecurityState;
   /**
    * The caller's expanded capability set — raw scope + pdf bits +
-   * implication rules, enumerated for DISPLAY ("here's what you can
+   * implication rules, enumerated for display ("here's what you can
    * do"). Identical shape on local and cloud; cloud uses the
    * server-canonical value when available, else computes locally from
    * JWT scope + /head bits.
    *
-   * NOTE: this is an *enumeration*, not an authorization check. The `*`
-   * admin wildcard and unbounded parametric collab grants are NOT
+   * Note: this is an *enumeration*, not an authorization check. The `*`
+   * admin wildcard and unbounded parametric collab grants are not
    * listed here (they can't be). To gate UI, use {@link allows} — the
    * same wildcard-aware predicate the engine enforces with.
    */
-  readonly effectiveScope: ReadonlyArray<string>;
+  readonly scope: ReadonlyArray<string>;
   /**
-   * Wildcard-aware authorization check — the SAME predicate the engine
+   * Wildcard-aware authorization check — the same predicate the engine
    * enforces with (`checkCapability`). A shown control gated on this
    * mirrors exactly what the engine will allow: the `*` admin grant and
    * `pdf.permissions`-derived bits are both honored. Use this for edit
-   * gating (e.g. `allows('doc.pages.assemble')`); use `effectiveScope`
-   * only to *display* the concrete grants.
+   * gating (e.g. `allows('doc.pages.assemble')`); use `scope` only to
+   * *display* the concrete grants.
    */
   allows(capability: DocCapability): boolean;
   /**
-   * Per-record annotation authorization mirrors — the SAME resolver the
+   * Per-record annotation authorization mirrors — the same resolver the
    * engine enforces with (`checkCollab`'s narrowing rule: an applicable
-   * `annotations:<action>:<filter>` grant SHADOWS the coarse
+   * `annotations:<action>:<filter>` grant shadows the coarse
    * `doc.annotate.modify` fallback for that action), over the same
    * inputs (raw scope + identity claims + PDF bits). `allows()` cannot
    * answer these: it enumerates capabilities, and a filtered collab
    * grant is not a capability — whether "update" is allowed depends on
-   * WHOSE annotation you're touching.
+   * whose annotation you're touching.
    *
-   * Three surfaces because the questions genuinely differ:
-   *   - create derives its target from the caller's OWN identity
-   *     (`:self` trivially passes; `:group=X` matches the caller's
-   *     default group),
-   *   - update/delete are asked about the TARGET record's stamped
-   *     owner (`userId`/`groupId` from its EMBD metadata; pass `{}`
-   *     when unstamped — matching the engine, which denies unstamped
-   *     targets under any narrowed grant),
-   *   - group assignment is asked about the DESTINATION group
-   *     (`annotations:set-group:` ladder; the caller's own default
-   *     group is always assignable).
+   * The target depends on the action:
+   *   - `create` needs none: it derives the target from the caller's
+   *     own identity (`:self` trivially passes; `:group=X` matches the
+   *     caller's default group),
+   *   - `update`/`delete` take the annotation itself, asked about its
+   *     stamped owner (`userId`/`groupId`; an unstamped annotation is
+   *     denied under any narrowed grant, as the engine does),
+   *   - `set-group` takes the destination group (`annotations:set-group:`
+   *     ladder; the caller's own default group is always assignable).
    *
    * These are a courtesy for UI gating — the engine (and the server,
    * on cloud) independently enforces every mutation with the same
@@ -340,13 +299,42 @@ interface DocumentSecurityService {
    * access. Returns false when no scope context exists (legacy local
    * open without `scope`, cloud open without a token before /access).
    */
-  allowsAnnotationCreate(): boolean;
-  allowsAnnotationMutation(action: 'update' | 'delete', target: CollabTarget): boolean;
-  allowsAnnotationGroupAssignment(groupId: string): boolean;
+  allowsAnnotation(action: 'create'): boolean;
+  allowsAnnotation(action: 'update' | 'delete', annotation: AnnotationOwner): boolean;
+  allowsAnnotation(action: 'set-group', target: {
+    groupId: string;
+  }): boolean;
+  /**
+   * Per-field form authorization, mirroring what the engine checks on every
+   * fill, signing and form design write:
+   *   - `fill`/`sign` take the field (its `groupId`): a `fields:fill` /
+   *     `fields:sign` scope for its group, or, without one, `doc.forms.fill`
+   *     / `doc.sign` for every field;
+   *   - `set-group` takes the destination group (`fields:set-group:` ladder;
+   *     the caller's own default group is always assignable).
+   *
+   * A courtesy for UI gating, like {@link allowsAnnotation}: the engine
+   * enforces every write with the same predicates.
+   */
+  allowsField(action: 'fill' | 'sign', field: {
+    groupId: string | null;
+  }): boolean;
+  allowsField(action: 'set-group', target: {
+    groupId: string;
+  }): boolean;
+  /**
+   * The same rules as {@link allowsField}, as lists: for filling in, signing
+   * and putting a field in a group, every field (`{ all: true }`) or the
+   * groups the session's scope names. A form designer offers exactly these
+   * groups, and a filler sees whose fields are theirs. A courtesy for UI,
+   * like `allowsField`.
+   */
+  fieldRights(): FieldRights;
   /**
-   * Identity of the current caller, or null when anonymous.
+   * Who the session acts for: from the document token's `identity` claim on
+   * the cloud, from `engine.open()` locally. Null when anonymous.
    */
-  readonly identity: IdentityClaims | null;
+  readonly identity: Identity | null;
   /**
    * "Should I prompt the user for a password?" — the single source
    * of truth. Three states, each carrying exactly the data needed:
@@ -359,5 +347,5 @@ interface DocumentSecurityService {
   unlock(input: DocumentUnlockInput): AbortablePromise<DocumentUnlockResult>;
 }
 //#endregion
-export { DocumentEncryptionState as a, DocumentSecurityState as c, PdfPermissionAdvisory as d, PdfPermissionInfo as f, AbortablePromise as g, AbortableExecutor as h, DocumentAccessReason as i, DocumentUnlockInput as l, passwordPromptFromState as m, CdnAdapter as n, DocumentOpenMode as o, PasswordPrompt as p, DocumentAccessInfo as r, DocumentSecurityService as s, CdnAccessInfo as t, DocumentUnlockResult as u };
-//# sourceMappingURL=DocumentSecurityService-_JRjqvoI.d.ts.map
+export { DocumentAccessReason as a, DocumentSecurityService as c, DocumentUnlockResult as d, PdfPermissionAdvisory as f, passwordPromptFromState as h, DocumentAccessInfo as i, DocumentSecurityState as l, PasswordPrompt as m, CdnAccessInfo as n, DocumentEncryptionState as o, PdfPermissionInfo as p, CdnAdapter as r, DocumentOpenMode as s, AnnotationOwner as t, DocumentUnlockInput as u };
+//# sourceMappingURL=DocumentSecurityService-CU1M6Q7m.d.ts.map

package/dist/{DocumentSecurityService-ClTZc0zO.d.cts → DocumentSecurityService-e6vp2de8.d.cts}

@@ -1,77 +1,16 @@
-import { Su as PdfBits, gu as IdentityClaims, hl as CollabTarget, hu as DocCapability } from "./AnnotationListSnapshot-D3mFut1e.cjs";
-//#region src/promise/AbortablePromise.d.ts
-type AbortableExecutor<T, P> = (resolve: (value: T | PromiseLike<T>) => void, reject: (reason: unknown) => void, progress: (p: P) => void, signal: AbortSignal) => void;
-/**
- * Awaitable Promise subclass with abort and progress.
- *
- * Symbol.species returns plain Promise so chained .then/.catch/.finally
- * return regular promises and never try to synthesize a new
- * AbortablePromise (which would have no executor).
- *
- * Settlement contract:
- *   - The first settlement wins. resolve/reject handed to the executor
- *     are wrapped so that any subsequent call (whether by the executor,
- *     by abort(), or by both racing) becomes a silent no-op.
- *   - abort() rejects the public promise with AbortError immediately,
- *     even if the executor never observes the AbortSignal. The executor
- *     still receives the AbortSignal so it can stop real work
- *     cooperatively (release a queue slot, abort fetch, post a worker
- *     abort, etc.). Anything the executor does after that — including
- *     a late resolve(value), a late reject(error), or a rejected inner
- *     Promise inside AbortablePromise.run — is dropped silently.
- *   - abort() after settlement is a no-op.
- */
-declare class AbortablePromise<T, P = never> extends Promise<T> {
-  static get [Symbol.species](): PromiseConstructor;
-  readonly signal: AbortSignal;
-  private readonly _ctrl;
-  private readonly _progressCbs;
-  private readonly _state;
-  private readonly _internalReject;
-  constructor(executor: AbortableExecutor<T, P>);
-  /**
-   * Abort the underlying operation.
-   *
-   * - If the promise has already settled, this is a no-op.
-   * - Otherwise the public promise rejects synchronously with an
-   *   AbortError (wrapping the supplied reason if it is not already an
-   *   AbortError) and the AbortSignal fires for any cooperative
-   *   cancellation the executor wired up.
-   */
-  abort(reason?: unknown): void;
-  /**
-   * Subscribe to progress events. Returns an unsubscribe function.
-   */
-  onProgress(cb: (p: P) => void): () => void;
-  /**
-   * Wrap a value in an already-resolved AbortablePromise. Mirrors Promise.resolve.
-   */
-  static resolveValue<T>(value: T | PromiseLike<T>): AbortablePromise<T>;
-  /**
-   * Wrap a thrown reason in an already-rejected AbortablePromise.
-   */
-  static rejectReason<T = never>(reason: unknown): AbortablePromise<T>;
-  /**
-   * Run an async function as an AbortablePromise so callers get .abort() and .signal.
-   * The async function receives the AbortSignal (and a progress emitter) so it can
-   * cooperate with the abort.
-   *
-   * If abort() fires while the inner async function is still running, the
-   * public promise rejects with AbortError immediately. The inner async
-   * function's eventual settlement (resolve or reject) is funneled through
-   * the wrapped settlers and silently dropped — including a late rejection
-   * from the underlying work, which prevents an UnhandledRejection because
-   * the .then(resolve, reject) below "handles" it via the no-op.
-   */
-  static run<T, P = never>(fn: (signal: AbortSignal, progress: (p: P) => void) => Promise<T>): AbortablePromise<T, P>;
-}
-//#endregion
+import { C_ as DocCapability, Du as BundleLimits, E_ as Identity, M_ as PdfBits, P_ as AbortablePromise, Wh as DocumentProtection, Xd as EditSessionAccess, ph as FieldRights } from "./AnnotationList-CkijRHet.cjs";
 //#region src/engine/passwordPrompt.d.ts
 type PasswordPrompt = {
   readonly state: 'none';
 } | {
   readonly state: 'required';
   readonly hint: 'user' | 'owner' | null;
+  /**
+   * The last password tried (at `open()` or `unlock()`) was wrong, so a
+   * prompt can say so. A wrong password opens the document locked, as no
+   * password does: one path for "this file needs a password".
+   */
+  readonly incorrect: boolean;
 } | {
   readonly state: 'optional';
   readonly hint: 'owner';
@@ -80,7 +19,7 @@ type PasswordPrompt = {
  * Derive the high-level password prompt from the raw security state.
  *
  * The function is pure and total — every `DocumentSecurityState`
- * maps to exactly one `PasswordPrompt`. Use this as the SINGLE source
+ * maps to exactly one `PasswordPrompt`. Use this as the single source
  * of truth wherever the SDK exposes a "do you need a password?" flag:
  * both `LocalDocumentSecurityService` and `CloudDocumentSecurityService`
  * call it, so the contract can never drift.
@@ -110,7 +49,7 @@ type PasswordPrompt = {
  *
  *   6. fallthrough → { state: 'none' }   open and nothing more available
  */
-declare function passwordPromptFromState(state: DocumentSecurityState): PasswordPrompt;
+declare function passwordPromptFromState(state: DocumentSecurityState, incorrect?: boolean): PasswordPrompt;
 //#endregion
 //#region src/engine/DocumentSecurityService.d.ts
 type DocumentOpenMode = 'none' | 'user' | 'owner';
@@ -123,10 +62,9 @@ type DocumentAccessReason = 'password' | 'cdn' | 'permissions-unknown';
  * not the raw bit names — so docs can render "Print: disabled" without
  * the reader needing to know PDF bit positions.
  *
- * Computed from {@link PdfBits} via the strict ISO 32000 rules:
- *   bit 12 only meaningful when bit 3 is also set
- *   form modification requires both bit 6 AND bit 4
- *   form fill is satisfied by bit 6 OR bit 9
+ * Computed from {@link PdfBits} as `pdf.permissions` reads them, which
+ * is what Acrobat allows on the file: for example, form fill comes with
+ * bit 4, 6 or 9, and form modification needs both bit 4 and bit 6.
  */
 interface PdfPermissionAdvisory {
   readonly canPrint: boolean;
@@ -240,12 +178,13 @@ interface DocumentAccessInfo {
    * Sorted alphabetically for stable display.
    */
   readonly effectiveScope: string[];
-  readonly identity: {
-    readonly user_id?: string;
-    readonly group_id?: string;
-    readonly groups?: string[];
-    readonly display_name?: string;
-  };
+  /**
+   * What the document's signatures forbid (`null` when it has none): a
+   * certification or a signed lock takes capabilities away from every
+   * caller, and `effectiveScope` already leaves them out.
+   */
+  readonly protection: DocumentProtection | null;
+  readonly identity: Identity;
   readonly originPasswordPolicy: {
     readonly mode: 'not-needed' | 'client-retry' | 'server-session';
   };
@@ -255,7 +194,7 @@ interface DocumentAccessInfo {
    * `viewport.width` points whose renders are durable, CDN-shared
    * artifacts, plus the reserved tile-pyramid block. Local engines report
    * nothing here (continuous rendering); cloud engines surface it so
-   * `snapFullPageViewport` can conform requests EXPLICITLY — the SDK
+   * `snapFullPageViewport` can conform requests explicitly — the SDK
    * never snaps implicitly (engine parity).
    */
   readonly renderPolicy?: {
@@ -274,6 +213,17 @@ interface DocumentAccessInfo {
     readonly background: 'white';
     readonly enforced: boolean;
   };
+  /**
+   * The deployment's limits for an annotation import: the cloud client
+   * checks a bundle against these before its bytes move.
+   */
+  readonly bundleLimits: BundleLimits;
+  /**
+   * The caller's editing session and the object numbers handed to it,
+   * present when the caller may create objects and named its session
+   * (`X-Engine-Session-Id`).
+   */
+  readonly edit?: EditSessionAccess;
 }
 interface DocumentUnlockInput {
   readonly password: string;
@@ -283,56 +233,65 @@ interface DocumentUnlockResult {
   readonly security: DocumentSecurityState;
   readonly access?: DocumentAccessInfo;
 }
+/**
+ * What an annotation is and whose: what `allowsAnnotation('update' |
+ * 'delete', …)` reads. An `Annotation` is one; so is `{ userId, groupId }`.
+ * A widget (`subtype: 'widget'`) belongs to a form field: changing or
+ * deleting one takes `doc.forms.modify`, whoever's it is.
+ */
+interface AnnotationOwner {
+  subtype?: string;
+  userId?: string | null;
+  groupId?: string | null;
+}
 interface DocumentSecurityService {
   /**
    * Raw structured security probe. Stable across engines, refreshed
-   * after unlock/refresh. Power users and diagnostic tools read this;
-   * most dev code uses the higher-level accessors below.
+   * after an unlock. Power users and diagnostic tools read this; most
+   * code uses the higher-level accessors below.
    */
-  readonly current: DocumentSecurityState;
+  readonly state: DocumentSecurityState;
   /**
    * The caller's expanded capability set — raw scope + pdf bits +
-   * implication rules, enumerated for DISPLAY ("here's what you can
+   * implication rules, enumerated for display ("here's what you can
    * do"). Identical shape on local and cloud; cloud uses the
    * server-canonical value when available, else computes locally from
    * JWT scope + /head bits.
    *
-   * NOTE: this is an *enumeration*, not an authorization check. The `*`
-   * admin wildcard and unbounded parametric collab grants are NOT
+   * Note: this is an *enumeration*, not an authorization check. The `*`
+   * admin wildcard and unbounded parametric collab grants are not
    * listed here (they can't be). To gate UI, use {@link allows} — the
    * same wildcard-aware predicate the engine enforces with.
    */
-  readonly effectiveScope: ReadonlyArray<string>;
+  readonly scope: ReadonlyArray<string>;
   /**
-   * Wildcard-aware authorization check — the SAME predicate the engine
+   * Wildcard-aware authorization check — the same predicate the engine
    * enforces with (`checkCapability`). A shown control gated on this
    * mirrors exactly what the engine will allow: the `*` admin grant and
    * `pdf.permissions`-derived bits are both honored. Use this for edit
-   * gating (e.g. `allows('doc.pages.assemble')`); use `effectiveScope`
-   * only to *display* the concrete grants.
+   * gating (e.g. `allows('doc.pages.assemble')`); use `scope` only to
+   * *display* the concrete grants.
    */
   allows(capability: DocCapability): boolean;
   /**
-   * Per-record annotation authorization mirrors — the SAME resolver the
+   * Per-record annotation authorization mirrors — the same resolver the
    * engine enforces with (`checkCollab`'s narrowing rule: an applicable
-   * `annotations:<action>:<filter>` grant SHADOWS the coarse
+   * `annotations:<action>:<filter>` grant shadows the coarse
    * `doc.annotate.modify` fallback for that action), over the same
    * inputs (raw scope + identity claims + PDF bits). `allows()` cannot
    * answer these: it enumerates capabilities, and a filtered collab
    * grant is not a capability — whether "update" is allowed depends on
-   * WHOSE annotation you're touching.
+   * whose annotation you're touching.
    *
-   * Three surfaces because the questions genuinely differ:
-   *   - create derives its target from the caller's OWN identity
-   *     (`:self` trivially passes; `:group=X` matches the caller's
-   *     default group),
-   *   - update/delete are asked about the TARGET record's stamped
-   *     owner (`userId`/`groupId` from its EMBD metadata; pass `{}`
-   *     when unstamped — matching the engine, which denies unstamped
-   *     targets under any narrowed grant),
-   *   - group assignment is asked about the DESTINATION group
-   *     (`annotations:set-group:` ladder; the caller's own default
-   *     group is always assignable).
+   * The target depends on the action:
+   *   - `create` needs none: it derives the target from the caller's
+   *     own identity (`:self` trivially passes; `:group=X` matches the
+   *     caller's default group),
+   *   - `update`/`delete` take the annotation itself, asked about its
+   *     stamped owner (`userId`/`groupId`; an unstamped annotation is
+   *     denied under any narrowed grant, as the engine does),
+   *   - `set-group` takes the destination group (`annotations:set-group:`
+   *     ladder; the caller's own default group is always assignable).
    *
    * These are a courtesy for UI gating — the engine (and the server,
    * on cloud) independently enforces every mutation with the same
@@ -340,13 +299,42 @@ interface DocumentSecurityService {
    * access. Returns false when no scope context exists (legacy local
    * open without `scope`, cloud open without a token before /access).
    */
-  allowsAnnotationCreate(): boolean;
-  allowsAnnotationMutation(action: 'update' | 'delete', target: CollabTarget): boolean;
-  allowsAnnotationGroupAssignment(groupId: string): boolean;
+  allowsAnnotation(action: 'create'): boolean;
+  allowsAnnotation(action: 'update' | 'delete', annotation: AnnotationOwner): boolean;
+  allowsAnnotation(action: 'set-group', target: {
+    groupId: string;
+  }): boolean;
+  /**
+   * Per-field form authorization, mirroring what the engine checks on every
+   * fill, signing and form design write:
+   *   - `fill`/`sign` take the field (its `groupId`): a `fields:fill` /
+   *     `fields:sign` scope for its group, or, without one, `doc.forms.fill`
+   *     / `doc.sign` for every field;
+   *   - `set-group` takes the destination group (`fields:set-group:` ladder;
+   *     the caller's own default group is always assignable).
+   *
+   * A courtesy for UI gating, like {@link allowsAnnotation}: the engine
+   * enforces every write with the same predicates.
+   */
+  allowsField(action: 'fill' | 'sign', field: {
+    groupId: string | null;
+  }): boolean;
+  allowsField(action: 'set-group', target: {
+    groupId: string;
+  }): boolean;
+  /**
+   * The same rules as {@link allowsField}, as lists: for filling in, signing
+   * and putting a field in a group, every field (`{ all: true }`) or the
+   * groups the session's scope names. A form designer offers exactly these
+   * groups, and a filler sees whose fields are theirs. A courtesy for UI,
+   * like `allowsField`.
+   */
+  fieldRights(): FieldRights;
   /**
-   * Identity of the current caller, or null when anonymous.
+   * Who the session acts for: from the document token's `identity` claim on
+   * the cloud, from `engine.open()` locally. Null when anonymous.
    */
-  readonly identity: IdentityClaims | null;
+  readonly identity: Identity | null;
   /**
    * "Should I prompt the user for a password?" — the single source
    * of truth. Three states, each carrying exactly the data needed:
@@ -359,5 +347,5 @@ interface DocumentSecurityService {
   unlock(input: DocumentUnlockInput): AbortablePromise<DocumentUnlockResult>;
 }
 //#endregion
-export { DocumentEncryptionState as a, DocumentSecurityState as c, PdfPermissionAdvisory as d, PdfPermissionInfo as f, AbortablePromise as g, AbortableExecutor as h, DocumentAccessReason as i, DocumentUnlockInput as l, passwordPromptFromState as m, CdnAdapter as n, DocumentOpenMode as o, PasswordPrompt as p, DocumentAccessInfo as r, DocumentSecurityService as s, CdnAccessInfo as t, DocumentUnlockResult as u };
-//# sourceMappingURL=DocumentSecurityService-ClTZc0zO.d.cts.map
+export { DocumentAccessReason as a, DocumentSecurityService as c, DocumentUnlockResult as d, PdfPermissionAdvisory as f, passwordPromptFromState as h, DocumentAccessInfo as i, DocumentSecurityState as l, PasswordPrompt as m, CdnAccessInfo as n, DocumentEncryptionState as o, PdfPermissionInfo as p, CdnAdapter as r, DocumentOpenMode as s, AnnotationOwner as t, DocumentUnlockInput as u };
+//# sourceMappingURL=DocumentSecurityService-e6vp2de8.d.cts.map