@embedpdf/engine-core 3.0.0-next.0

package/dist/DocumentSecurityService-B-tULKNY.d.ts

@@ -0,0 +1,332 @@
+import { Hs as DocCapability, Us as IdentityClaims, Ys as PdfBits } from "./AnnotationListSnapshot-W0RCsyDE.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
+//#region src/engine/passwordPrompt.d.ts
+type PasswordPrompt = {
+  readonly state: 'none';
+} | {
+  readonly state: 'required';
+  readonly hint: 'user' | 'owner' | null;
+} | {
+  readonly state: 'optional';
+  readonly hint: 'owner';
+};
+/**
+ * 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
+ * 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.
+ *
+ * Mapping rules (top to bottom; first match wins):
+ *
+ *   1. encryption.state === 'none'
+ *      → { state: 'none' }              the document isn't encrypted
+ *
+ *   2. !permissions.known
+ *      → { state: 'required', hint: null }   we haven't probed yet; can't
+ *                                            tell user-vs-owner; show
+ *                                            generic prompt
+ *
+ *   3. requiresPassword && openedAs === 'none'
+ *      → { state: 'required', hint: 'user' }   encrypted, anonymous open
+ *                                              failed → user pwd needed
+ *
+ *   4. openedAs === 'owner'
+ *      → { state: 'none' }              already at the top — nothing more
+ *                                       to unlock
+ *
+ *   5. permissions.canUpgradeToOwner === true
+ *      → { state: 'optional', hint: 'owner' }   open as user (or as none
+ *                                               for owner-pwd-only docs)
+ *                                               but more is available
+ *
+ *   6. fallthrough → { state: 'none' }   open and nothing more available
+ */
+declare function passwordPromptFromState(state: DocumentSecurityState): PasswordPrompt;
+//#endregion
+//#region src/engine/DocumentSecurityService.d.ts
+type DocumentOpenMode = 'none' | 'user' | 'owner';
+type DocumentEncryptionState = 'unknown' | 'none' | 'encrypted' | 'unsupported';
+type DocumentAccessReason = 'password' | 'cdn' | 'permissions-unknown';
+/**
+ * Boolean view of "what the PDF's permission bits allow," surfaced for
+ * client UI badges ("this PDF disallows printing", "copy is blocked",
+ * etc.). Names mirror the user-facing capability they correspond to,
+ * 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
+ */
+interface PdfPermissionAdvisory {
+  readonly canPrint: boolean;
+  readonly canPrintHigh: boolean;
+  readonly canCopy: boolean;
+  readonly canAnnotate: boolean;
+  readonly canFillForms: boolean;
+  readonly canModifyForms: boolean;
+  readonly canModifyPages: boolean;
+  readonly canAssemble: boolean;
+}
+interface PdfPermissionInfo {
+  readonly known: boolean;
+  readonly allAllowed: boolean | null;
+  readonly bits: number | null;
+  readonly openedAs: DocumentOpenMode | null;
+  readonly securityHandlerRevision: number | null;
+  /**
+   * Typed boolean view of `bits`. Present whenever the caller had
+   * access to the document's PDF bits at construction time (always
+   * true in the /access response; not always populated by the cheaper
+   * /head shape).
+   */
+  readonly flags?: PdfBits;
+  /**
+   * Capability-shaped "what does this PDF natively allow" view for UI
+   * badges. Same population rule as `flags`.
+   */
+  readonly advisory?: PdfPermissionAdvisory;
+}
+interface DocumentSecurityState {
+  readonly encryption: {
+    readonly state: DocumentEncryptionState;
+    readonly requiresPassword: boolean | null;
+  };
+  readonly permissions: {
+    readonly known: boolean;
+    readonly bits: number | null;
+    readonly allAllowed: boolean | null;
+    readonly openedAs: DocumentOpenMode | null;
+    readonly securityHandlerRevision: number | null;
+    readonly canUpgradeToOwner: boolean;
+  };
+  readonly access: {
+    readonly required: boolean;
+    readonly reasons: DocumentAccessReason[];
+    readonly endpoint?: string;
+  };
+}
+/**
+ * The CDN adapter identifier surfaced on the wire. Cloudflare users
+ * deploy a custom Worker that verifies HMAC-SHA256 signatures and
+ * configure the `custom-hmac` adapter — no first-class `'cloudflare'`
+ * value is needed.
+ */
+type CdnAdapter = 'none' | 'cloudfront' | 'cloud-cdn' | 'bunny' | 'azure-fd' | 'custom-hmac';
+/**
+ * Per-caller CDN access bits returned in the /access response. The
+ * SDK fetch wrapper applies whatever channels are populated:
+ *   - baseUrlOverrides   : swap the origin host/path-prefix for the CDN URL
+ *   - authHeader         : attach a single header to every CDN request
+ *   - signedQueryParams  : append params to every CDN URL (single-token signers)
+ *   - signedCookies      : set cookies on the CDN origin before requests
+ *   - signedPathPolicies : per-prefix params (one signature covers a path subtree)
+ *
+ * Each adapter populates only the channels it uses; the others stay
+ * null. Frontend stays provider-agnostic — it doesn't branch on
+ * `adapter`, it just applies whatever's present.
+ */
+interface CdnAccessInfo {
+  readonly adapter: CdnAdapter;
+  readonly expiresAt: number;
+  readonly cache: {
+    readonly scope: 'browser-private' | 'edge-shared';
+    readonly immutableVersionedReads: boolean;
+  };
+  readonly baseUrlOverrides: Partial<Record<string, string>> | null;
+  readonly authHeader: {
+    name: string;
+    value: string;
+  } | null;
+  readonly signedQueryParams: Record<string, string> | null;
+  readonly signedCookies: ReadonlyArray<{
+    readonly name: string;
+    readonly value: string;
+    readonly domain?: string;
+    readonly path?: string;
+    readonly expires?: number;
+  }> | null;
+  readonly signedPathPolicies: ReadonlyArray<{
+    readonly pathPrefix: string;
+    readonly queryParams: Record<string, string>;
+  }> | null;
+}
+interface DocumentAccessInfo {
+  readonly cdn: CdnAccessInfo;
+  readonly passwordGrant: string | null;
+  readonly pdfPermissions: PdfPermissionInfo | null;
+  /**
+   * Raw scope array exactly as the JWT carried it. Useful for debugging
+   * and for clients that want to display the literal grants.
+   */
+  readonly scope: string[];
+  /**
+   * Concrete capability set granted to this caller, after expanding
+   * `pdf.permissions` against the document's PDF bits and applying
+   * the implication rules in the resolver (e.g. annotation collab
+   * scopes imply `doc.annotate.read`). Client UI should drive feature
+   * visibility off this, not off the raw `scope`.
+   *
+   * 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;
+  };
+  readonly originPasswordPolicy: {
+    readonly mode: 'not-needed' | 'client-retry' | 'server-session';
+  };
+  readonly expiresAt: number;
+  /**
+   * The deployment's render lattice: canonical full-page
+   * `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
+   * never snaps implicitly (engine parity).
+   */
+  readonly renderPolicy?: {
+    readonly fullPage: {
+      readonly widths: readonly number[];
+    };
+    readonly tiles?: {
+      readonly tileSizes: readonly number[];
+      readonly scales: readonly number[];
+    };
+    readonly appearances?: {
+      readonly scales: readonly number[];
+    };
+    readonly maxRenderPixels?: number;
+    readonly formats: readonly ('webp' | 'png')[];
+    readonly background: 'white';
+    readonly enforced: boolean;
+  };
+}
+interface DocumentUnlockInput {
+  readonly password: string;
+  readonly mode?: 'any' | 'owner';
+}
+interface DocumentUnlockResult {
+  readonly security: DocumentSecurityState;
+  readonly access?: DocumentAccessInfo;
+}
+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.
+   */
+  readonly current: DocumentSecurityState;
+  /**
+   * The caller's expanded capability set — raw scope + pdf bits +
+   * 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
+   * 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>;
+  /**
+   * 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.
+   */
+  allows(capability: DocCapability): boolean;
+  /**
+   * Identity of the current caller, or null when anonymous.
+   */
+  readonly identity: IdentityClaims | null;
+  /**
+   * "Should I prompt the user for a password?" — the single source
+   * of truth. Three states, each carrying exactly the data needed:
+   *   - `none`     — do nothing
+   *   - `required` — hard block; show modal; `hint` labels the prompt
+   *   - `optional` — soft offer; show banner; only ever asks for owner
+   * See {@link PasswordPrompt} for the full contract.
+   */
+  readonly passwordPrompt: PasswordPrompt;
+  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-B-tULKNY.d.ts.map

package/dist/DocumentSecurityService-Df79fgpe.d.cts

@@ -0,0 +1,332 @@
+import { Hs as DocCapability, Us as IdentityClaims, Ys as PdfBits } from "./AnnotationListSnapshot-W0RCsyDE.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
+//#region src/engine/passwordPrompt.d.ts
+type PasswordPrompt = {
+  readonly state: 'none';
+} | {
+  readonly state: 'required';
+  readonly hint: 'user' | 'owner' | null;
+} | {
+  readonly state: 'optional';
+  readonly hint: 'owner';
+};
+/**
+ * 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
+ * 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.
+ *
+ * Mapping rules (top to bottom; first match wins):
+ *
+ *   1. encryption.state === 'none'
+ *      → { state: 'none' }              the document isn't encrypted
+ *
+ *   2. !permissions.known
+ *      → { state: 'required', hint: null }   we haven't probed yet; can't
+ *                                            tell user-vs-owner; show
+ *                                            generic prompt
+ *
+ *   3. requiresPassword && openedAs === 'none'
+ *      → { state: 'required', hint: 'user' }   encrypted, anonymous open
+ *                                              failed → user pwd needed
+ *
+ *   4. openedAs === 'owner'
+ *      → { state: 'none' }              already at the top — nothing more
+ *                                       to unlock
+ *
+ *   5. permissions.canUpgradeToOwner === true
+ *      → { state: 'optional', hint: 'owner' }   open as user (or as none
+ *                                               for owner-pwd-only docs)
+ *                                               but more is available
+ *
+ *   6. fallthrough → { state: 'none' }   open and nothing more available
+ */
+declare function passwordPromptFromState(state: DocumentSecurityState): PasswordPrompt;
+//#endregion
+//#region src/engine/DocumentSecurityService.d.ts
+type DocumentOpenMode = 'none' | 'user' | 'owner';
+type DocumentEncryptionState = 'unknown' | 'none' | 'encrypted' | 'unsupported';
+type DocumentAccessReason = 'password' | 'cdn' | 'permissions-unknown';
+/**
+ * Boolean view of "what the PDF's permission bits allow," surfaced for
+ * client UI badges ("this PDF disallows printing", "copy is blocked",
+ * etc.). Names mirror the user-facing capability they correspond to,
+ * 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
+ */
+interface PdfPermissionAdvisory {
+  readonly canPrint: boolean;
+  readonly canPrintHigh: boolean;
+  readonly canCopy: boolean;
+  readonly canAnnotate: boolean;
+  readonly canFillForms: boolean;
+  readonly canModifyForms: boolean;
+  readonly canModifyPages: boolean;
+  readonly canAssemble: boolean;
+}
+interface PdfPermissionInfo {
+  readonly known: boolean;
+  readonly allAllowed: boolean | null;
+  readonly bits: number | null;
+  readonly openedAs: DocumentOpenMode | null;
+  readonly securityHandlerRevision: number | null;
+  /**
+   * Typed boolean view of `bits`. Present whenever the caller had
+   * access to the document's PDF bits at construction time (always
+   * true in the /access response; not always populated by the cheaper
+   * /head shape).
+   */
+  readonly flags?: PdfBits;
+  /**
+   * Capability-shaped "what does this PDF natively allow" view for UI
+   * badges. Same population rule as `flags`.
+   */
+  readonly advisory?: PdfPermissionAdvisory;
+}
+interface DocumentSecurityState {
+  readonly encryption: {
+    readonly state: DocumentEncryptionState;
+    readonly requiresPassword: boolean | null;
+  };
+  readonly permissions: {
+    readonly known: boolean;
+    readonly bits: number | null;
+    readonly allAllowed: boolean | null;
+    readonly openedAs: DocumentOpenMode | null;
+    readonly securityHandlerRevision: number | null;
+    readonly canUpgradeToOwner: boolean;
+  };
+  readonly access: {
+    readonly required: boolean;
+    readonly reasons: DocumentAccessReason[];
+    readonly endpoint?: string;
+  };
+}
+/**
+ * The CDN adapter identifier surfaced on the wire. Cloudflare users
+ * deploy a custom Worker that verifies HMAC-SHA256 signatures and
+ * configure the `custom-hmac` adapter — no first-class `'cloudflare'`
+ * value is needed.
+ */
+type CdnAdapter = 'none' | 'cloudfront' | 'cloud-cdn' | 'bunny' | 'azure-fd' | 'custom-hmac';
+/**
+ * Per-caller CDN access bits returned in the /access response. The
+ * SDK fetch wrapper applies whatever channels are populated:
+ *   - baseUrlOverrides   : swap the origin host/path-prefix for the CDN URL
+ *   - authHeader         : attach a single header to every CDN request
+ *   - signedQueryParams  : append params to every CDN URL (single-token signers)
+ *   - signedCookies      : set cookies on the CDN origin before requests
+ *   - signedPathPolicies : per-prefix params (one signature covers a path subtree)
+ *
+ * Each adapter populates only the channels it uses; the others stay
+ * null. Frontend stays provider-agnostic — it doesn't branch on
+ * `adapter`, it just applies whatever's present.
+ */
+interface CdnAccessInfo {
+  readonly adapter: CdnAdapter;
+  readonly expiresAt: number;
+  readonly cache: {
+    readonly scope: 'browser-private' | 'edge-shared';
+    readonly immutableVersionedReads: boolean;
+  };
+  readonly baseUrlOverrides: Partial<Record<string, string>> | null;
+  readonly authHeader: {
+    name: string;
+    value: string;
+  } | null;
+  readonly signedQueryParams: Record<string, string> | null;
+  readonly signedCookies: ReadonlyArray<{
+    readonly name: string;
+    readonly value: string;
+    readonly domain?: string;
+    readonly path?: string;
+    readonly expires?: number;
+  }> | null;
+  readonly signedPathPolicies: ReadonlyArray<{
+    readonly pathPrefix: string;
+    readonly queryParams: Record<string, string>;
+  }> | null;
+}
+interface DocumentAccessInfo {
+  readonly cdn: CdnAccessInfo;
+  readonly passwordGrant: string | null;
+  readonly pdfPermissions: PdfPermissionInfo | null;
+  /**
+   * Raw scope array exactly as the JWT carried it. Useful for debugging
+   * and for clients that want to display the literal grants.
+   */
+  readonly scope: string[];
+  /**
+   * Concrete capability set granted to this caller, after expanding
+   * `pdf.permissions` against the document's PDF bits and applying
+   * the implication rules in the resolver (e.g. annotation collab
+   * scopes imply `doc.annotate.read`). Client UI should drive feature
+   * visibility off this, not off the raw `scope`.
+   *
+   * 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;
+  };
+  readonly originPasswordPolicy: {
+    readonly mode: 'not-needed' | 'client-retry' | 'server-session';
+  };
+  readonly expiresAt: number;
+  /**
+   * The deployment's render lattice: canonical full-page
+   * `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
+   * never snaps implicitly (engine parity).
+   */
+  readonly renderPolicy?: {
+    readonly fullPage: {
+      readonly widths: readonly number[];
+    };
+    readonly tiles?: {
+      readonly tileSizes: readonly number[];
+      readonly scales: readonly number[];
+    };
+    readonly appearances?: {
+      readonly scales: readonly number[];
+    };
+    readonly maxRenderPixels?: number;
+    readonly formats: readonly ('webp' | 'png')[];
+    readonly background: 'white';
+    readonly enforced: boolean;
+  };
+}
+interface DocumentUnlockInput {
+  readonly password: string;
+  readonly mode?: 'any' | 'owner';
+}
+interface DocumentUnlockResult {
+  readonly security: DocumentSecurityState;
+  readonly access?: DocumentAccessInfo;
+}
+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.
+   */
+  readonly current: DocumentSecurityState;
+  /**
+   * The caller's expanded capability set — raw scope + pdf bits +
+   * 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
+   * 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>;
+  /**
+   * 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.
+   */
+  allows(capability: DocCapability): boolean;
+  /**
+   * Identity of the current caller, or null when anonymous.
+   */
+  readonly identity: IdentityClaims | null;
+  /**
+   * "Should I prompt the user for a password?" — the single source
+   * of truth. Three states, each carrying exactly the data needed:
+   *   - `none`     — do nothing
+   *   - `required` — hard block; show modal; `hint` labels the prompt
+   *   - `optional` — soft offer; show banner; only ever asks for owner
+   * See {@link PasswordPrompt} for the full contract.
+   */
+  readonly passwordPrompt: PasswordPrompt;
+  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-Df79fgpe.d.cts.map