@embedpdf/engine-core 3.0.0-next.0

package/dist/resolver-DAZWVoJL.cjs

@@ -0,0 +1,434 @@
+//#region src/auth/scope/errors.ts
+/**
+* Thrown by {@link parseScope} / {@link validateScopeArray} when a scope
+* string does not match any known grammar (capability, collab, virtual,
+* or wildcard).
+*
+* Carries the offending scope verbatim so route/JWT-layer error
+* handlers can echo it to the customer.
+*/
+var InvalidScope = class extends Error {
+	constructor(scope, reason) {
+		super(`invalid scope "${scope}": ${reason}`);
+		this.scope = scope;
+		this.name = "InvalidScope";
+	}
+};
+/**
+* Thrown by route guards and engine-local enforcement when a capability
+* or collab action is denied for the current request/handle.
+*
+* `required` names what the caller needed (e.g., "doc.render" or
+* "annotations:update"). `context` is an optional label such as "local"
+* or "/v1/docs/.../pages/2/render".
+*/
+var PermissionDenied = class extends Error {
+	constructor(required, context) {
+		super(`permission denied${context ? ` (${context})` : ""}: ${required}`);
+		this.required = required;
+		this.context = context;
+		this.name = "PermissionDenied";
+	}
+};
+/**
+* Thrown at engine-local open time when the supplied scope includes
+* collab filters (`:self`, `:group=...`) but the identity claims needed
+* to resolve them are missing. Fails loudly at open so the configuration
+* mistake is visible immediately instead of producing silent denies at
+* every annotation mutation.
+*/
+var MissingIdentity = class extends Error {
+	constructor(scope) {
+		super(`scope "${scope}" requires identity claims (user_id and/or groups)`);
+		this.name = "MissingIdentity";
+	}
+};
+//#endregion
+//#region src/auth/scope/parser.ts
+/**
+* Closed set of recognized capability strings. Membership is the
+* authoritative source of truth — adding a new capability requires
+* extending the `DocCapability` union AND adding it here. The parser
+* rejects anything outside this set.
+*
+* Removed legacy names (e.g., `doc.read`, `doc.edit-pages`, `doc.save`)
+* are deliberately absent so any JWT carrying them fails at verify
+* time with a clear error.
+*/
+const KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
+	"doc.open",
+	"doc.render",
+	"doc.text.select",
+	"doc.text.copy",
+	"doc.text.search",
+	"doc.content.copy",
+	"doc.download",
+	"doc.download.flattened",
+	"doc.print",
+	"doc.print.high",
+	"doc.pages.modify",
+	"doc.pages.assemble",
+	"doc.forms.read",
+	"doc.forms.fill",
+	"doc.forms.modify",
+	"doc.annotate.read",
+	"doc.annotate.modify",
+	"doc.metadata.modify",
+	"doc.attachments.modify",
+	"doc.redact"
+]);
+/**
+* Parse a single scope string into a structured `ParsedScope`.
+*
+* Recognised shapes:
+*   - `"*"`                              → wildcard
+*   - `"pdf.permissions"`                → virtual (expands at resolve time)
+*   - `"a.b.c..."` (dotted)              → capability
+*   - `"entity:action:filter"` (colons)  → collab
+*
+* Throws {@link InvalidScope} for any string that fails to match one of
+* those shapes, or whose capability/entity/action/filter is not in the
+* closed enum.
+*/
+function parseScope(raw) {
+	if (raw === "*") return { kind: "wildcard" };
+	if (raw === "pdf.permissions") return {
+		kind: "virtual",
+		name: "pdf.permissions"
+	};
+	if (raw.includes(":")) return parseCollab(raw);
+	return parseCapability(raw);
+}
+/**
+* Validate every entry in a scope array by attempting to parse it.
+* Throws on the first invalid string. Discards the parse output —
+* callers re-parse at resolution time to keep the array as the
+* authoritative payload.
+*/
+function validateScopeArray(raw) {
+	for (const s of raw) parseScope(s);
+}
+function parseCollab(raw) {
+	const idx1 = raw.indexOf(":");
+	const idx2 = raw.indexOf(":", idx1 + 1);
+	if (idx1 === -1 || idx2 === -1) throw new InvalidScope(raw, "collab scope requires entity:action:filter");
+	const entity = raw.slice(0, idx1);
+	const action = raw.slice(idx1 + 1, idx2);
+	const filterStr = raw.slice(idx2 + 1);
+	if (entity !== "annotations") throw new InvalidScope(raw, `unknown collab entity: ${entity}`);
+	if (action !== "create" && action !== "update" && action !== "delete" && action !== "set-group" && action !== "*") throw new InvalidScope(raw, `unknown collab action: ${action}`);
+	const filter = parseFilter(filterStr, raw);
+	if (action === "set-group" && (filter.kind === "self" || filter.kind === "createdBy")) throw new InvalidScope(raw, `set-group only supports :all or :group=<id> filters (got :${filter.kind})`);
+	return {
+		kind: "collab",
+		entity,
+		action,
+		filter
+	};
+}
+function parseFilter(s, raw) {
+	if (s === "all") return { kind: "all" };
+	if (s === "self") return { kind: "self" };
+	if (s.startsWith("createdBy=")) {
+		const v = s.slice(10);
+		if (!v) throw new InvalidScope(raw, "createdBy= requires a value");
+		return {
+			kind: "createdBy",
+			userId: v
+		};
+	}
+	if (s.startsWith("group=")) {
+		const v = s.slice(6);
+		if (!v) throw new InvalidScope(raw, "group= requires a value");
+		return {
+			kind: "group",
+			groupId: v
+		};
+	}
+	throw new InvalidScope(raw, `unknown filter: ${s}`);
+}
+const CAPABILITY_SHAPE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+function parseCapability(raw) {
+	if (!CAPABILITY_SHAPE.test(raw)) throw new InvalidScope(raw, "invalid capability name shape");
+	if (!KNOWN_CAPABILITIES.has(raw)) throw new InvalidScope(raw, `unknown capability: ${raw}`);
+	return {
+		kind: "capability",
+		name: raw
+	};
+}
+//#endregion
+//#region src/auth/scope/resolver.ts
+/**
+* True iff the given capability is granted by the scope array plus the
+* PDF bits visible via `pdf.permissions` expansion.
+*
+* Wildcard `*` short-circuits to true. Anything not explicitly granted
+* (or expanded from `pdf.permissions`) is denied.
+*/
+function checkCapability(capability, rawScope, pdfBits) {
+	const parsed = rawScope.map(parseScope);
+	if (parsed.some((s) => s.kind === "wildcard")) return true;
+	return expandedCapabilities(parsed, pdfBits).has(capability);
+}
+/**
+* True iff the scope grants AT LEAST ONE of `capabilities`. Convenience
+* for routes like `/text` (`doc.text.copy` OR `doc.text.search`) and
+* `/geometry` (`doc.text.select` OR `doc.text.search`).
+*/
+function checkAnyCapability(capabilities, rawScope, pdfBits) {
+	return capabilities.some((c) => checkCapability(c, rawScope, pdfBits));
+}
+/**
+* True iff the scope grants the collab action against the target record.
+*
+* Narrowing model. For each action independently:
+*   1. wildcard `*` → allow (global escape hatch)
+*   2. if any collab scope applies to this action → NARROW: only those
+*      collab filters decide. If none match the target, deny — even if
+*      `doc.annotate.modify` is also present. This is what makes
+*      `[modify, update:self]` correctly mean "edit own only" rather
+*      than "edit anyone via modify-bypass."
+*   3. otherwise, if `doc.annotate.modify` is present → allow. This is
+*      the broad PDF-bit-derived default for create/update/delete when
+*      no per-action collab filter has been written.
+*   4. otherwise → deny.
+*
+* For create: `target` should be built by the caller from JWT identity
+* (`{ userId: caller.user_id, groupId: caller.group_id }`). `:self` and
+* `:all` then trivially pass; `:group=X` is the meaningful filter (only
+* matches when the caller's default group is X).
+*
+* For update / delete: `target` is the existing row's owner.
+*/
+function checkCollab(action, target, rawScope, identity, pdfBits) {
+	const parsed = rawScope.map(parseScope);
+	if (parsed.some((s) => s.kind === "wildcard")) return true;
+	const applicableCollab = parsed.filter((s) => s.kind === "collab" && s.entity === "annotations" && (s.action === action || s.action === "*"));
+	if (applicableCollab.length > 0) return applicableCollab.some((s) => filterMatches(s.filter, target, identity));
+	return expandedCapabilities(parsed, pdfBits).has("doc.annotate.modify");
+}
+/**
+* Compute the full set of granted capabilities after expanding
+* `pdf.permissions` and applying implication rules.
+*
+* Implications applied:
+*   - `doc.annotate.modify` implies `doc.annotate.read` (you can't
+*     sensibly modify what you can't see).
+*   - `doc.forms.modify` implies `doc.forms.fill` and `doc.forms.read`.
+*   - `doc.forms.fill`   implies `doc.forms.read`.
+*   - any annotation collab scope implies `doc.annotate.read`, because
+*     mutation routes need to see the target row to evaluate the
+*     collab filter against its current owner.
+*
+* Does NOT short-circuit on wildcard — callers do that themselves
+* before calling this. Returning the expanded set is useful for the
+* `/access` response's `effectiveScope` and for advisory UI surfacing.
+*/
+function expandedCapabilities(parsed, pdfBits) {
+	const out = /* @__PURE__ */ new Set();
+	let hasAnnotationCollab = false;
+	for (const s of parsed) if (s.kind === "capability") out.add(s.name);
+	else if (s.kind === "virtual" && s.name === "pdf.permissions") addPdfPermissions(out, pdfBits);
+	else if (s.kind === "collab" && s.entity === "annotations") hasAnnotationCollab = true;
+	if (out.has("doc.annotate.modify")) out.add("doc.annotate.read");
+	if (out.has("doc.forms.modify")) {
+		out.add("doc.forms.fill");
+		out.add("doc.forms.read");
+	}
+	if (out.has("doc.forms.fill")) out.add("doc.forms.read");
+	if (hasAnnotationCollab) out.add("doc.annotate.read");
+	return out;
+}
+/**
+* Convenience wrapper: takes the raw scope array, parses each entry,
+* returns the expanded capability set. Exposed for the `/access`
+* endpoint and for the SDK helper that surfaces `effectiveScope`.
+*/
+function expandRawScope(rawScope, pdfBits) {
+	return expandedCapabilities(rawScope.map(parseScope), pdfBits);
+}
+/**
+* Test a single collab filter against a target record + the caller's
+* identity. Pure function — no side effects, no implicit rules.
+*
+*   all              → always matches
+*   self             → matches if identity.user_id === target.userId
+*   createdBy=<X>    → matches if target.userId === X
+*   group=<X>        → matches if target.groupId === X
+*                      AND identity.groups includes X
+*
+* The group-membership check on `group=X` prevents a token from
+* matching annotations in a group it doesn't belong to, even if the
+* target row carries that groupId.
+*/
+/**
+* Authority to assign a specific groupId to an annotation.
+*
+* Set-group is decoupled from `doc.annotate.modify`. The reasoning:
+* capabilities like `modify` describe row access — what kind of write
+* you can do to which existing rows — and map to PDF permission bits.
+* Set-group is a cloud-only *assignment authority*: which destination
+* group can you put an annotation into? There is no PDF-bit
+* counterpart, so it doesn't inherit from `modify`.
+*
+* Resolution order:
+*   1. newGroupId === callerDefaultGroupId → true (no real reassignment
+*      is happening; the annotation gets the caller's default group)
+*   2. wildcard `*` → true (global escape hatch)
+*   3. `annotations:set-group:all` → true
+*   4. `annotations:set-group:group=<newGroupId>` → true
+*   5. `annotations:*:all` or `annotations:*:group=<newGroupId>` → true
+*      (action wildcard includes set-group)
+*   6. otherwise → false
+*
+* Note: independent from membership. A user with
+* `set-group:group=legal` can assign annotations to the legal group
+* even if they're not a member — that's the whole point.
+*/
+function checkSetGroup(newGroupId, callerDefaultGroupId, rawScope, _pdfBits) {
+	if (newGroupId === callerDefaultGroupId) return true;
+	const parsed = rawScope.map(parseScope);
+	if (parsed.some((s) => s.kind === "wildcard")) return true;
+	for (const s of parsed) {
+		if (s.kind !== "collab") continue;
+		if (s.entity !== "annotations") continue;
+		if (s.action !== "set-group" && s.action !== "*") continue;
+		if (s.filter.kind === "all") return true;
+		if (s.filter.kind === "group" && s.filter.groupId === newGroupId) return true;
+	}
+	return false;
+}
+function filterMatches(filter, target, id) {
+	switch (filter.kind) {
+		case "all": return true;
+		case "self": return !!id.user_id && target.userId === id.user_id;
+		case "createdBy": return target.userId === filter.userId;
+		case "group": return target.groupId === filter.groupId && (id.groups?.includes(filter.groupId) ?? false);
+	}
+}
+/**
+* Translate `pdf.permissions` (virtual scope) into the concrete
+* capabilities it represents under the current PDF bit configuration.
+*
+* Always adds `doc.open` and `doc.render` — these are cloud-only
+* capabilities with no PDF bit, but `pdf.permissions` is meant to be
+* the "give the user a working session" shorthand. Without them, a
+* token with just `['pdf.permissions']` would be useless.
+*
+* Reads are unconditional: ISO 32000 / Acrobat let any reader see
+* existing annotations and form values regardless of permission bits.
+* Bit 6 governs *writing*, not visibility.
+*
+* Bit-derived expansions follow ISO 32000:
+*   bit 5   → doc.text.{select, copy, search}, doc.content.copy
+*   bit 3   → doc.print
+*   bit 12  → doc.print.high (requires bit 3 also set)
+*   bit 4   → doc.pages.modify, doc.redact, doc.metadata.modify, doc.attachments.modify
+*   bit 11  → doc.pages.assemble
+*   bit 6   → doc.annotate.modify
+*   bit 6/9 → doc.forms.fill
+*   bit 6+4 → doc.forms.modify
+*
+* Note: this same expansion lives in builders.ts as
+* `materializePdfPermissions` for SDK-side use. The two MUST stay in
+* sync; a test in resolver.test.ts pins them together.
+*/
+function addPdfPermissions(out, b) {
+	out.add("doc.open");
+	out.add("doc.render");
+	out.add("doc.annotate.read");
+	out.add("doc.forms.read");
+	if (b.bit5) {
+		out.add("doc.text.select");
+		out.add("doc.text.copy");
+		out.add("doc.text.search");
+		out.add("doc.content.copy");
+	}
+	if (b.bit3) out.add("doc.print");
+	if (b.bit12 && b.bit3) out.add("doc.print.high");
+	if (b.bit4) {
+		out.add("doc.pages.modify");
+		out.add("doc.redact");
+		out.add("doc.metadata.modify");
+		out.add("doc.attachments.modify");
+	}
+	if (b.bit11) out.add("doc.pages.assemble");
+	if (b.bit6) out.add("doc.annotate.modify");
+	if (b.bit6 || b.bit9) out.add("doc.forms.fill");
+	if (b.bit6 && b.bit4) out.add("doc.forms.modify");
+}
+//#endregion
+Object.defineProperty(exports, "InvalidScope", {
+	enumerable: true,
+	get: function() {
+		return InvalidScope;
+	}
+});
+Object.defineProperty(exports, "MissingIdentity", {
+	enumerable: true,
+	get: function() {
+		return MissingIdentity;
+	}
+});
+Object.defineProperty(exports, "PermissionDenied", {
+	enumerable: true,
+	get: function() {
+		return PermissionDenied;
+	}
+});
+Object.defineProperty(exports, "checkAnyCapability", {
+	enumerable: true,
+	get: function() {
+		return checkAnyCapability;
+	}
+});
+Object.defineProperty(exports, "checkCapability", {
+	enumerable: true,
+	get: function() {
+		return checkCapability;
+	}
+});
+Object.defineProperty(exports, "checkCollab", {
+	enumerable: true,
+	get: function() {
+		return checkCollab;
+	}
+});
+Object.defineProperty(exports, "checkSetGroup", {
+	enumerable: true,
+	get: function() {
+		return checkSetGroup;
+	}
+});
+Object.defineProperty(exports, "expandRawScope", {
+	enumerable: true,
+	get: function() {
+		return expandRawScope;
+	}
+});
+Object.defineProperty(exports, "expandedCapabilities", {
+	enumerable: true,
+	get: function() {
+		return expandedCapabilities;
+	}
+});
+Object.defineProperty(exports, "filterMatches", {
+	enumerable: true,
+	get: function() {
+		return filterMatches;
+	}
+});
+Object.defineProperty(exports, "parseScope", {
+	enumerable: true,
+	get: function() {
+		return parseScope;
+	}
+});
+Object.defineProperty(exports, "validateScopeArray", {
+	enumerable: true,
+	get: function() {
+		return validateScopeArray;
+	}
+});
+
+//# sourceMappingURL=resolver-DAZWVoJL.cjs.map

package/dist/resolver-DAZWVoJL.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver-DAZWVoJL.cjs","names":[],"sources":["../src/auth/scope/errors.ts","../src/auth/scope/parser.ts","../src/auth/scope/resolver.ts"],"sourcesContent":["/**\n * Thrown by {@link parseScope} / {@link validateScopeArray} when a scope\n * string does not match any known grammar (capability, collab, virtual,\n * or wildcard).\n *\n * Carries the offending scope verbatim so route/JWT-layer error\n * handlers can echo it to the customer.\n */\nexport class InvalidScope extends Error {\n  constructor(\n    public readonly scope: string,\n    reason: string,\n  ) {\n    super(`invalid scope \"${scope}\": ${reason}`);\n    this.name = 'InvalidScope';\n  }\n}\n\n/**\n * Thrown by route guards and engine-local enforcement when a capability\n * or collab action is denied for the current request/handle.\n *\n * `required` names what the caller needed (e.g., \"doc.render\" or\n * \"annotations:update\"). `context` is an optional label such as \"local\"\n * or \"/v1/docs/.../pages/2/render\".\n */\nexport class PermissionDenied extends Error {\n  constructor(\n    public readonly required: string,\n    public readonly context?: string,\n  ) {\n    super(`permission denied${context ? ` (${context})` : ''}: ${required}`);\n    this.name = 'PermissionDenied';\n  }\n}\n\n/**\n * Thrown at engine-local open time when the supplied scope includes\n * collab filters (`:self`, `:group=...`) but the identity claims needed\n * to resolve them are missing. Fails loudly at open so the configuration\n * mistake is visible immediately instead of producing silent denies at\n * every annotation mutation.\n */\nexport class MissingIdentity extends Error {\n  constructor(scope: string) {\n    super(`scope \"${scope}\" requires identity claims (user_id and/or groups)`);\n    this.name = 'MissingIdentity';\n  }\n}\n","import { InvalidScope } from './errors';\nimport type { CollabAction, CollabFilter, DocCapability, ParsedScope } from './types';\n\n/**\n * Closed set of recognized capability strings. Membership is the\n * authoritative source of truth — adding a new capability requires\n * extending the `DocCapability` union AND adding it here. The parser\n * rejects anything outside this set.\n *\n * Removed legacy names (e.g., `doc.read`, `doc.edit-pages`, `doc.save`)\n * are deliberately absent so any JWT carrying them fails at verify\n * time with a clear error.\n */\nconst KNOWN_CAPABILITIES: ReadonlySet<DocCapability> = new Set([\n  'doc.open',\n  'doc.render',\n  'doc.text.select',\n  'doc.text.copy',\n  'doc.text.search',\n  'doc.content.copy',\n  'doc.download',\n  'doc.download.flattened',\n  'doc.print',\n  'doc.print.high',\n  'doc.pages.modify',\n  'doc.pages.assemble',\n  'doc.forms.read',\n  'doc.forms.fill',\n  'doc.forms.modify',\n  'doc.annotate.read',\n  'doc.annotate.modify',\n  'doc.metadata.modify',\n  'doc.attachments.modify',\n  'doc.redact',\n]);\n\n/**\n * Parse a single scope string into a structured `ParsedScope`.\n *\n * Recognised shapes:\n *   - `\"*\"`                              → wildcard\n *   - `\"pdf.permissions\"`                → virtual (expands at resolve time)\n *   - `\"a.b.c...\"` (dotted)              → capability\n *   - `\"entity:action:filter\"` (colons)  → collab\n *\n * Throws {@link InvalidScope} for any string that fails to match one of\n * those shapes, or whose capability/entity/action/filter is not in the\n * closed enum.\n */\nexport function parseScope(raw: string): ParsedScope {\n  if (raw === '*') return { kind: 'wildcard' };\n  if (raw === 'pdf.permissions') return { kind: 'virtual', name: 'pdf.permissions' };\n  if (raw.includes(':')) return parseCollab(raw);\n  return parseCapability(raw);\n}\n\n/**\n * Validate every entry in a scope array by attempting to parse it.\n * Throws on the first invalid string. Discards the parse output —\n * callers re-parse at resolution time to keep the array as the\n * authoritative payload.\n */\nexport function validateScopeArray(raw: ReadonlyArray<string>): void {\n  for (const s of raw) parseScope(s);\n}\n\nfunction parseCollab(raw: string): ParsedScope {\n  // Split on the FIRST two colons only. Filter values may contain\n  // colons (UUIDs with `urn:uuid:...`, subject ids like `auth0|user:1`).\n  const idx1 = raw.indexOf(':');\n  const idx2 = raw.indexOf(':', idx1 + 1);\n  if (idx1 === -1 || idx2 === -1) {\n    throw new InvalidScope(raw, 'collab scope requires entity:action:filter');\n  }\n  const entity = raw.slice(0, idx1);\n  const action = raw.slice(idx1 + 1, idx2);\n  const filterStr = raw.slice(idx2 + 1);\n\n  if (entity !== 'annotations') {\n    throw new InvalidScope(raw, `unknown collab entity: ${entity}`);\n  }\n  if (\n    action !== 'create' &&\n    action !== 'update' &&\n    action !== 'delete' &&\n    action !== 'set-group' &&\n    action !== '*'\n  ) {\n    throw new InvalidScope(raw, `unknown collab action: ${action}`);\n  }\n  const filter = parseFilter(filterStr, raw);\n\n  // `set-group` is a group-assignment authority, not a per-record collab\n  // filter. The only meaningful filter values are `all` (assign to any\n  // group) and `group=X` (assign to group X). `:self` and `:createdBy=Y`\n  // can't be sensibly applied to \"what group is this annotation in\", so\n  // we reject them at parse time rather than silently always-denying.\n  if (action === 'set-group' && (filter.kind === 'self' || filter.kind === 'createdBy')) {\n    throw new InvalidScope(\n      raw,\n      `set-group only supports :all or :group=<id> filters (got :${filter.kind})`,\n    );\n  }\n\n  return {\n    kind: 'collab',\n    entity,\n    action: action as CollabAction | '*',\n    filter,\n  };\n}\n\nfunction parseFilter(s: string, raw: string): CollabFilter {\n  if (s === 'all') return { kind: 'all' };\n  if (s === 'self') return { kind: 'self' };\n  if (s.startsWith('createdBy=')) {\n    const v = s.slice('createdBy='.length);\n    if (!v) throw new InvalidScope(raw, 'createdBy= requires a value');\n    return { kind: 'createdBy', userId: v };\n  }\n  if (s.startsWith('group=')) {\n    const v = s.slice('group='.length);\n    if (!v) throw new InvalidScope(raw, 'group= requires a value');\n    return { kind: 'group', groupId: v };\n  }\n  throw new InvalidScope(raw, `unknown filter: ${s}`);\n}\n\n// Capability shape: lowercase dotted segments, e.g. \"doc.text.copy\".\n// Validates shape first, then membership in the closed set.\nconst CAPABILITY_SHAPE = /^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$/;\n\nfunction parseCapability(raw: string): ParsedScope {\n  if (!CAPABILITY_SHAPE.test(raw)) {\n    throw new InvalidScope(raw, 'invalid capability name shape');\n  }\n  if (!KNOWN_CAPABILITIES.has(raw as DocCapability)) {\n    throw new InvalidScope(raw, `unknown capability: ${raw}`);\n  }\n  return { kind: 'capability', name: raw as DocCapability };\n}\n","import { parseScope } from './parser';\nimport type {\n  CollabAction,\n  CollabFilter,\n  DocCapability,\n  IdentityClaims,\n  ParsedScope,\n  PdfBits,\n} from './types';\n\n/**\n * Resolved collab subject — the per-record identity bits used to test\n * collab filters against. Sourced from the target record's stored\n * `/EMBD_Metadata/UserID` and `/GroupID` at mutation time.\n */\nexport interface CollabTarget {\n  userId?: string;\n  groupId?: string;\n}\n\n/**\n * True iff the given capability is granted by the scope array plus the\n * PDF bits visible via `pdf.permissions` expansion.\n *\n * Wildcard `*` short-circuits to true. Anything not explicitly granted\n * (or expanded from `pdf.permissions`) is denied.\n */\nexport function checkCapability(\n  capability: DocCapability,\n  rawScope: ReadonlyArray<string>,\n  pdfBits: PdfBits,\n): boolean {\n  const parsed = rawScope.map(parseScope);\n  if (parsed.some((s) => s.kind === 'wildcard')) return true;\n  return expandedCapabilities(parsed, pdfBits).has(capability);\n}\n\n/**\n * True iff the scope grants AT LEAST ONE of `capabilities`. Convenience\n * for routes like `/text` (`doc.text.copy` OR `doc.text.search`) and\n * `/geometry` (`doc.text.select` OR `doc.text.search`).\n */\nexport function checkAnyCapability(\n  capabilities: ReadonlyArray<DocCapability>,\n  rawScope: ReadonlyArray<string>,\n  pdfBits: PdfBits,\n): boolean {\n  return capabilities.some((c) => checkCapability(c, rawScope, pdfBits));\n}\n\n/**\n * True iff the scope grants the collab action against the target record.\n *\n * Narrowing model. For each action independently:\n *   1. wildcard `*` → allow (global escape hatch)\n *   2. if any collab scope applies to this action → NARROW: only those\n *      collab filters decide. If none match the target, deny — even if\n *      `doc.annotate.modify` is also present. This is what makes\n *      `[modify, update:self]` correctly mean \"edit own only\" rather\n *      than \"edit anyone via modify-bypass.\"\n *   3. otherwise, if `doc.annotate.modify` is present → allow. This is\n *      the broad PDF-bit-derived default for create/update/delete when\n *      no per-action collab filter has been written.\n *   4. otherwise → deny.\n *\n * For create: `target` should be built by the caller from JWT identity\n * (`{ userId: caller.user_id, groupId: caller.group_id }`). `:self` and\n * `:all` then trivially pass; `:group=X` is the meaningful filter (only\n * matches when the caller's default group is X).\n *\n * For update / delete: `target` is the existing row's owner.\n */\nexport function checkCollab(\n  action: CollabAction,\n  target: CollabTarget,\n  rawScope: ReadonlyArray<string>,\n  identity: IdentityClaims,\n  pdfBits: PdfBits,\n): boolean {\n  const parsed = rawScope.map(parseScope);\n  if (parsed.some((s) => s.kind === 'wildcard')) return true;\n\n  const applicableCollab = parsed.filter(\n    (s): s is Extract<ParsedScope, { kind: 'collab' }> =>\n      s.kind === 'collab' &&\n      s.entity === 'annotations' &&\n      (s.action === action || s.action === '*'),\n  );\n\n  if (applicableCollab.length > 0) {\n    // Narrow: presence of any applicable collab scope shadows\n    // `modify`-as-default for this action.\n    return applicableCollab.some((s) => filterMatches(s.filter, target, identity));\n  }\n\n  // No collab scope for this action — fall back to the broad default.\n  return expandedCapabilities(parsed, pdfBits).has('doc.annotate.modify');\n}\n\n/**\n * Compute the full set of granted capabilities after expanding\n * `pdf.permissions` and applying implication rules.\n *\n * Implications applied:\n *   - `doc.annotate.modify` implies `doc.annotate.read` (you can't\n *     sensibly modify what you can't see).\n *   - `doc.forms.modify` implies `doc.forms.fill` and `doc.forms.read`.\n *   - `doc.forms.fill`   implies `doc.forms.read`.\n *   - any annotation collab scope implies `doc.annotate.read`, because\n *     mutation routes need to see the target row to evaluate the\n *     collab filter against its current owner.\n *\n * Does NOT short-circuit on wildcard — callers do that themselves\n * before calling this. Returning the expanded set is useful for the\n * `/access` response's `effectiveScope` and for advisory UI surfacing.\n */\nexport function expandedCapabilities(\n  parsed: ReadonlyArray<ParsedScope>,\n  pdfBits: PdfBits,\n): Set<DocCapability> {\n  const out = new Set<DocCapability>();\n  let hasAnnotationCollab = false;\n\n  for (const s of parsed) {\n    if (s.kind === 'capability') {\n      out.add(s.name);\n    } else if (s.kind === 'virtual' && s.name === 'pdf.permissions') {\n      addPdfPermissions(out, pdfBits);\n    } else if (s.kind === 'collab' && s.entity === 'annotations') {\n      hasAnnotationCollab = true;\n    }\n  }\n\n  // Implications (apply after the explicit additions above)\n  if (out.has('doc.annotate.modify')) out.add('doc.annotate.read');\n  if (out.has('doc.forms.modify')) {\n    out.add('doc.forms.fill');\n    out.add('doc.forms.read');\n  }\n  if (out.has('doc.forms.fill')) out.add('doc.forms.read');\n  if (hasAnnotationCollab) out.add('doc.annotate.read');\n\n  return out;\n}\n\n/**\n * Convenience wrapper: takes the raw scope array, parses each entry,\n * returns the expanded capability set. Exposed for the `/access`\n * endpoint and for the SDK helper that surfaces `effectiveScope`.\n */\nexport function expandRawScope(\n  rawScope: ReadonlyArray<string>,\n  pdfBits: PdfBits,\n): Set<DocCapability> {\n  return expandedCapabilities(rawScope.map(parseScope), pdfBits);\n}\n\n/**\n * Test a single collab filter against a target record + the caller's\n * identity. Pure function — no side effects, no implicit rules.\n *\n *   all              → always matches\n *   self             → matches if identity.user_id === target.userId\n *   createdBy=<X>    → matches if target.userId === X\n *   group=<X>        → matches if target.groupId === X\n *                      AND identity.groups includes X\n *\n * The group-membership check on `group=X` prevents a token from\n * matching annotations in a group it doesn't belong to, even if the\n * target row carries that groupId.\n */\n/**\n * Authority to assign a specific groupId to an annotation.\n *\n * Set-group is decoupled from `doc.annotate.modify`. The reasoning:\n * capabilities like `modify` describe row access — what kind of write\n * you can do to which existing rows — and map to PDF permission bits.\n * Set-group is a cloud-only *assignment authority*: which destination\n * group can you put an annotation into? There is no PDF-bit\n * counterpart, so it doesn't inherit from `modify`.\n *\n * Resolution order:\n *   1. newGroupId === callerDefaultGroupId → true (no real reassignment\n *      is happening; the annotation gets the caller's default group)\n *   2. wildcard `*` → true (global escape hatch)\n *   3. `annotations:set-group:all` → true\n *   4. `annotations:set-group:group=<newGroupId>` → true\n *   5. `annotations:*:all` or `annotations:*:group=<newGroupId>` → true\n *      (action wildcard includes set-group)\n *   6. otherwise → false\n *\n * Note: independent from membership. A user with\n * `set-group:group=legal` can assign annotations to the legal group\n * even if they're not a member — that's the whole point.\n */\nexport function checkSetGroup(\n  newGroupId: string,\n  callerDefaultGroupId: string | undefined,\n  rawScope: ReadonlyArray<string>,\n  _pdfBits: PdfBits,\n): boolean {\n  // No authority needed when the caller is assigning their default group.\n  if (newGroupId === callerDefaultGroupId) return true;\n\n  const parsed = rawScope.map(parseScope);\n  if (parsed.some((s) => s.kind === 'wildcard')) return true;\n\n  for (const s of parsed) {\n    if (s.kind !== 'collab') continue;\n    if (s.entity !== 'annotations') continue;\n    if (s.action !== 'set-group' && s.action !== '*') continue;\n    if (s.filter.kind === 'all') return true;\n    if (s.filter.kind === 'group' && s.filter.groupId === newGroupId) return true;\n    // :self and :createdBy are rejected at parse time for set-group, so\n    // they never appear here. The action-wildcard path could carry those\n    // filters legitimately for other actions — silently skip those, they\n    // can't satisfy a set-group check.\n  }\n  return false;\n}\n\nexport function filterMatches(\n  filter: CollabFilter,\n  target: CollabTarget,\n  id: IdentityClaims,\n): boolean {\n  switch (filter.kind) {\n    case 'all':\n      return true;\n    case 'self':\n      return !!id.user_id && target.userId === id.user_id;\n    case 'createdBy':\n      return target.userId === filter.userId;\n    case 'group':\n      return target.groupId === filter.groupId && (id.groups?.includes(filter.groupId) ?? false);\n  }\n}\n\n/**\n * Translate `pdf.permissions` (virtual scope) into the concrete\n * capabilities it represents under the current PDF bit configuration.\n *\n * Always adds `doc.open` and `doc.render` — these are cloud-only\n * capabilities with no PDF bit, but `pdf.permissions` is meant to be\n * the \"give the user a working session\" shorthand. Without them, a\n * token with just `['pdf.permissions']` would be useless.\n *\n * Reads are unconditional: ISO 32000 / Acrobat let any reader see\n * existing annotations and form values regardless of permission bits.\n * Bit 6 governs *writing*, not visibility.\n *\n * Bit-derived expansions follow ISO 32000:\n *   bit 5   → doc.text.{select, copy, search}, doc.content.copy\n *   bit 3   → doc.print\n *   bit 12  → doc.print.high (requires bit 3 also set)\n *   bit 4   → doc.pages.modify, doc.redact, doc.metadata.modify, doc.attachments.modify\n *   bit 11  → doc.pages.assemble\n *   bit 6   → doc.annotate.modify\n *   bit 6/9 → doc.forms.fill\n *   bit 6+4 → doc.forms.modify\n *\n * Note: this same expansion lives in builders.ts as\n * `materializePdfPermissions` for SDK-side use. The two MUST stay in\n * sync; a test in resolver.test.ts pins them together.\n */\nfunction addPdfPermissions(out: Set<DocCapability>, b: PdfBits): void {\n  // Always — pdf.permissions means \"give me a working session\"\n  out.add('doc.open');\n  out.add('doc.render');\n  // Reading existing annotations and form values is unconditional —\n  // PDF bit 6 governs writes, not visibility.\n  out.add('doc.annotate.read');\n  out.add('doc.forms.read');\n\n  if (b.bit5) {\n    out.add('doc.text.select');\n    out.add('doc.text.copy');\n    out.add('doc.text.search');\n    out.add('doc.content.copy');\n  }\n  if (b.bit3) out.add('doc.print');\n  if (b.bit12 && b.bit3) out.add('doc.print.high');\n  if (b.bit4) {\n    out.add('doc.pages.modify');\n    out.add('doc.redact');\n    out.add('doc.metadata.modify');\n    out.add('doc.attachments.modify');\n  }\n  if (b.bit11) out.add('doc.pages.assemble');\n  if (b.bit6) {\n    out.add('doc.annotate.modify');\n  }\n  if (b.bit6 || b.bit9) out.add('doc.forms.fill');\n  if (b.bit6 && b.bit4) out.add('doc.forms.modify');\n}\n"],"mappings":"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"}