@gnolith/taproot 0.2.0 → 0.3.0

package/dist/authorization.js

@@ -0,0 +1,1137 @@
+import { AuthorizationDeniedError, InvalidAuthorizationError, InvalidCursorError, } from './errors.js';
+import { exportEntityJson } from './canonical.js';
+import { TaprootRepository } from './repository.js';
+export const SEARCH_ADMIN_CAPABILITY = 'search:admin';
+export const KNOWLEDGE_WRITE_CAPABILITY = 'knowledge:write';
+export const KNOWLEDGE_POLICY_CAPABILITY = 'knowledge:policy';
+const cursorCodecs = new WeakMap();
+export function createAuthorizationCursorCodec(key) {
+    if (key.type !== 'secret' ||
+        key.extractable ||
+        key.algorithm.name !== 'AES-GCM' ||
+        !key.usages.includes('encrypt') ||
+        !key.usages.includes('decrypt'))
+        invalid('cursor key must be a non-extractable AES-GCM key with encrypt/decrypt usages');
+    const codec = Object.freeze({ kind: 'taproot-aes-gcm-v1' });
+    cursorCodecs.set(codec, key);
+    return codec;
+}
+const MAX_IDENTIFIER_LENGTH = 256;
+const MAX_CLAUSES = 64;
+const MAX_ATOMS_PER_CLAUSE = 64;
+const CURSOR_AAD = new TextEncoder().encode('taproot-authorized-cursor-v1').buffer;
+const CURSOR_PLAINTEXT_BYTES = 1024;
+export function normalizeAuthorizationContext(value) {
+    if (!isRecord(value))
+        invalid('authorization context must be an object');
+    exactKeys(value, [
+        'installationId',
+        'principalId',
+        'activeWorkspaceId',
+        'workspaceIds',
+        'capabilities',
+        'authorizationRevision',
+    ]);
+    const installationId = identifier(value.installationId, 'installationId');
+    const principalId = identifier(value.principalId, 'principalId');
+    const activeWorkspaceId = value.activeWorkspaceId === null
+        ? null
+        : identifier(value.activeWorkspaceId, 'activeWorkspaceId');
+    const workspaceIds = stringSet(value.workspaceIds, 'workspaceIds');
+    const capabilities = stringSet(value.capabilities, 'capabilities');
+    const authorizationRevision = revision(value.authorizationRevision, 'authorizationRevision');
+    if (activeWorkspaceId !== null && !workspaceIds.includes(activeWorkspaceId))
+        invalid('activeWorkspaceId must be present in workspaceIds');
+    return {
+        installationId,
+        principalId,
+        activeWorkspaceId,
+        workspaceIds,
+        capabilities,
+        authorizationRevision,
+    };
+}
+export function normalizeVisibilityScope(value) {
+    if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.clauses))
+        invalid('visibility scope must be a version 1 CNF object');
+    exactKeys(value, ['version', 'clauses']);
+    if (value.clauses.length > MAX_CLAUSES)
+        invalid(`visibility scope exceeds ${MAX_CLAUSES} clauses`);
+    const clauses = new Map();
+    for (const rawClause of value.clauses) {
+        if (!Array.isArray(rawClause) || rawClause.length === 0)
+            invalid('visibility clauses must contain at least one atom');
+        if (rawClause.length > MAX_ATOMS_PER_CLAUSE)
+            invalid(`visibility clause exceeds ${MAX_ATOMS_PER_CLAUSE} atoms`);
+        const atoms = new Map();
+        let publicClause = false;
+        for (const rawAtom of rawClause) {
+            const atom = normalizeAtom(rawAtom);
+            if (atom.kind === 'public') {
+                publicClause = true;
+                break;
+            }
+            atoms.set(serializeAtom(atom), atom);
+        }
+        // A public OR-clause is true and therefore has no effect in an AND scope.
+        if (publicClause)
+            continue;
+        const sorted = [...atoms.entries()]
+            .sort(([left], [right]) => compareCodeUnits(left, right))
+            .map(([, atom]) => atom);
+        if (sorted.length === 0)
+            invalid('visibility clause is empty after normalization');
+        clauses.set(JSON.stringify(sorted), sorted);
+    }
+    return {
+        version: 1,
+        clauses: [...clauses.entries()]
+            .sort(([left], [right]) => compareCodeUnits(left, right))
+            .map(([, clause]) => clause),
+    };
+}
+export function serializeVisibilityScope(scope) {
+    return JSON.stringify(normalizeVisibilityScope(scope));
+}
+export async function visibilityScopeFingerprint(scope) {
+    const bytes = new TextEncoder().encode(serializeVisibilityScope(scope));
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}
+/** CNF intersection is lossless clause concatenation followed by normalization. */
+export function intersectVisibilityScopes(...scopes) {
+    return normalizeVisibilityScope({
+        version: 1,
+        clauses: scopes.flatMap((scope) => normalizeVisibilityScope(scope).clauses),
+    });
+}
+export function normalizeCanonicalAuthorizationPolicy(value) {
+    if (!isRecord(value))
+        invalid('authorization policy must be an object');
+    exactKeys(value, [
+        'installationId',
+        'workspaceId',
+        'ownerPrincipalId',
+        'visibility',
+        'statementRestrictions',
+        'expectedAuthorizationRevision',
+    ]);
+    if (!isRecord(value.statementRestrictions))
+        invalid('statementRestrictions must be an object');
+    const statementRestrictions = {};
+    for (const [statementId, scopes] of Object.entries(value.statementRestrictions).sort(([left], [right]) => compareCodeUnits(left, right))) {
+        identifier(statementId, 'statementId');
+        if (!Array.isArray(scopes))
+            invalid(`statementRestrictions.${statementId} must be an array`);
+        const normalizedScopes = [];
+        for (let index = 0; index < scopes.length; index += 1) {
+            if (!Object.hasOwn(scopes, index))
+                invalid(`statementRestrictions.${statementId} must be dense`);
+            normalizedScopes.push(normalizeVisibilityScope(scopes[index]));
+        }
+        statementRestrictions[statementId] = normalizedScopes;
+    }
+    return {
+        installationId: identifier(value.installationId, 'installationId'),
+        workspaceId: value.workspaceId === null
+            ? null
+            : identifier(value.workspaceId, 'workspaceId'),
+        ownerPrincipalId: identifier(value.ownerPrincipalId, 'ownerPrincipalId'),
+        visibility: normalizeVisibilityScope(value.visibility),
+        statementRestrictions,
+        expectedAuthorizationRevision: revision(value.expectedAuthorizationRevision, 'expectedAuthorizationRevision'),
+    };
+}
+export function isVisibleTo(rawScope, rawContext) {
+    const scope = normalizeVisibilityScope(rawScope);
+    const context = normalizeAuthorizationContext(rawContext);
+    const workspaces = new Set(context.workspaceIds);
+    const capabilities = new Set(context.capabilities);
+    return scope.clauses.every((clause) => clause.some((atom) => {
+        switch (atom.kind) {
+            case 'public':
+                return true;
+            case 'principal':
+                return atom.principalId === context.principalId;
+            case 'workspace':
+                return workspaces.has(atom.workspaceId);
+            case 'capability':
+                return capabilities.has(atom.capability);
+        }
+    }));
+}
+export function hasSearchAdministration(context) {
+    return normalizeAuthorizationContext(context).capabilities.includes(SEARCH_ADMIN_CAPABILITY);
+}
+export function requireSearchAdministration(context) {
+    if (!hasSearchAdministration(context))
+        throw new AuthorizationDeniedError('Authorization denied');
+}
+/**
+ * Authorization-enforcing canonical read boundary. The context and policy
+ * source are mandatory, and policy is checked both before and after hydration.
+ */
+export class AuthorizedTaprootReader {
+    #db;
+    #repository;
+    #context;
+    #authorization;
+    #cursorCodec;
+    constructor(db, options, context, authorizedOptions) {
+        this.#db = db;
+        this.#repository = new TaprootRepository(db, options);
+        this.#context = normalizeAuthorizationContext(context);
+        this.#authorization = new PersistedEntityAuthorizationSource(db);
+        if (!isRecord(authorizedOptions))
+            invalid('authorized options are required');
+        exactKeys(authorizedOptions, ['cursorCodec']);
+        if (!cursorCodecs.has(authorizedOptions.cursorCodec))
+            invalid('host-issued cursor codec is required');
+        this.#cursorCodec = authorizedOptions.cursorCodec;
+    }
+    async getEntity(id) {
+        return this.#authorizedHydration(id, undefined, () => this.#repository.getEntity(id));
+    }
+    async getEntityRevision(id, revisionNumber) {
+        return this.#authorizedHydration(id, revisionNumber, () => this.#repository.getEntityRevision(id, revisionNumber));
+    }
+    async resolveEntity(id, maxDepth = 100) {
+        if (!Number.isSafeInteger(maxDepth) || maxDepth < 0 || maxDepth > 1000)
+            throw new RangeError('maxDepth must be an integer from 0 through 1000');
+        const redirects = [];
+        const seen = new Set();
+        let current = id;
+        for (;;) {
+            if (seen.has(current))
+                throw new AuthorizationDeniedError('Authorization denied');
+            seen.add(current);
+            const stored = await this.getEntity(current);
+            if (!stored.redirectTo)
+                return { ...stored, requestedId: id, resolvedId: current, redirects };
+            if (redirects.length >= maxDepth)
+                throw new AuthorizationDeniedError('Authorization denied');
+            redirects.push(stored.redirectTo);
+            current = stored.redirectTo;
+        }
+    }
+    async listEntityRevisions(id, options = {}) {
+        const limit = authorizedLimit(options.limit, 50);
+        const binding = await this.#binding('entity-revisions', { id });
+        const generation = await this.#generation();
+        let before = Number.MAX_SAFE_INTEGER;
+        if (options.cursor) {
+            const cursor = await this.#decodeCursor(options.cursor, binding, generation);
+            before = cursorNumber(cursor.position, 'revision');
+        }
+        await this.#assertContextCurrent();
+        const items = [];
+        let exhausted = false;
+        while (items.length < limit && !exhausted) {
+            const batch = await this.#db
+                .prepare(`SELECT revision FROM taproot_entity_revisions
+           WHERE entity_id = ? AND revision < ?
+           ORDER BY revision DESC LIMIT ?`)
+                .bind(id, before, scanLimit(limit - items.length))
+                .all();
+            exhausted = batch.results.length < scanLimit(limit - items.length);
+            for (let index = 0; index < batch.results.length; index += 1) {
+                const candidate = batch.results[index];
+                before = candidate.revision;
+                try {
+                    items.push(await this.#authorizedHydration(id, candidate.revision, () => this.#repository.getEntityRevision(id, candidate.revision)));
+                }
+                catch (error) {
+                    if (!(error instanceof AuthorizationDeniedError))
+                        throw error;
+                }
+                if (items.length === limit) {
+                    if (index < batch.results.length - 1)
+                        exhausted = false;
+                    break;
+                }
+            }
+            if (!batch.results.length)
+                exhausted = true;
+        }
+        await this.#reauthorize(items.map(() => id));
+        await this.#assertGeneration(generation);
+        return {
+            items,
+            cursor: !exhausted && items.length
+                ? await this.#encodeCursor(binding, generation, { revision: before })
+                : null,
+        };
+    }
+    async listEntities(options = {}) {
+        const limit = authorizedLimit(options.limit, 50);
+        const filter = {
+            type: options.type ?? null,
+            includeDeleted: options.includeDeleted ?? false,
+        };
+        const binding = await this.#binding('entities', filter);
+        const generation = await this.#generation();
+        let position = null;
+        if (options.cursor) {
+            const cursor = await this.#decodeCursor(options.cursor, binding, generation);
+            position = entityPosition(cursor.position);
+        }
+        await this.#assertContextCurrent();
+        const items = [];
+        let exhausted = false;
+        while (items.length < limit && !exhausted) {
+            const amount = scanLimit(limit - items.length);
+            const result = await this.#db
+                .prepare(`SELECT entity_id, entity_type FROM taproot_entities
+           WHERE (? IS NULL OR entity_type > ? OR
+             (entity_type = ? AND CAST(substr(entity_id, 2) AS INTEGER) > ?))
+             AND (? IS NULL OR entity_type = ?)
+             AND (? = 1 OR deleted_at IS NULL)
+           ORDER BY entity_type, CAST(substr(entity_id, 2) AS INTEGER) LIMIT ?`)
+                .bind(position?.entityType ?? null, position?.entityType ?? null, position?.entityType ?? null, position?.numericId ?? 0, filter.type, filter.type, filter.includeDeleted ? 1 : 0, amount)
+                .all();
+            exhausted = result.results.length < amount;
+            for (let index = 0; index < result.results.length; index += 1) {
+                const candidate = result.results[index];
+                position = {
+                    entityType: candidate.entity_type,
+                    numericId: Number(candidate.entity_id.slice(1)),
+                };
+                try {
+                    const stored = await this.#authorizedHydration(candidate.entity_id, undefined, () => this.#repository.getEntity(candidate.entity_id));
+                    items.push({ entityId: candidate.entity_id, ...stored });
+                }
+                catch (error) {
+                    if (!(error instanceof AuthorizationDeniedError))
+                        throw error;
+                }
+                if (items.length === limit) {
+                    if (index < result.results.length - 1)
+                        exhausted = false;
+                    break;
+                }
+            }
+            if (!result.results.length)
+                exhausted = true;
+        }
+        await this.#reauthorize(items.map((item) => item.entityId));
+        await this.#assertGeneration(generation);
+        return {
+            items,
+            cursor: !exhausted && position
+                ? await this.#encodeCursor(binding, generation, position)
+                : null,
+        };
+    }
+    async searchEntities(query, options = {}) {
+        const limit = authorizedLimit(options.limit, 20);
+        const filter = {
+            query,
+            language: options.language ?? null,
+            includeDeleted: options.includeDeleted ?? false,
+        };
+        const binding = await this.#binding('term-search', filter);
+        const generation = await this.#generation();
+        let offset = 0;
+        if (options.cursor) {
+            const cursor = await this.#decodeCursor(options.cursor, binding, generation);
+            offset = cursorNumber(cursor.position, 'offset');
+        }
+        await this.#assertContextCurrent();
+        const escaped = query.replace(/[\\%_]/gu, '\\$&');
+        const items = [];
+        let exhausted = false;
+        while (items.length < limit && !exhausted) {
+            const amount = scanLimit(limit - items.length);
+            const candidates = await this.#db
+                .prepare(`SELECT t.entity_id
+           FROM taproot_terms t JOIN taproot_entities e ON e.entity_id = t.entity_id
+           WHERE t.value LIKE ? ESCAPE '\\' COLLATE NOCASE
+             AND (? IS NULL OR t.language = ?)
+             AND (? = 1 OR e.deleted_at IS NULL)
+           ORDER BY CASE WHEN t.value = ? COLLATE NOCASE THEN 0 ELSE 1 END,
+             t.value COLLATE NOCASE, t.entity_id, t.language, t.term_type, t.ordinal
+           LIMIT ? OFFSET ?`)
+                .bind(`%${escaped}%`, filter.language, filter.language, filter.includeDeleted ? 1 : 0, query, amount, offset)
+                .all();
+            exhausted = candidates.results.length < amount;
+            const batchOffset = offset;
+            for (let index = 0; index < candidates.results.length; index += 1) {
+                const candidate = candidates.results[index];
+                const candidateOffset = batchOffset + index;
+                try {
+                    const before = await this.#readAndAuthorize(candidate.entity_id);
+                    const hydrated = await this.#db
+                        .prepare(`SELECT t.entity_id, e.entity_type, t.language, t.term_type, t.value
+               FROM taproot_terms t JOIN taproot_entities e ON e.entity_id = t.entity_id
+               WHERE t.value LIKE ? ESCAPE '\\' COLLATE NOCASE
+                 AND (? IS NULL OR t.language = ?)
+                 AND (? = 1 OR e.deleted_at IS NULL)
+               ORDER BY CASE WHEN t.value = ? COLLATE NOCASE THEN 0 ELSE 1 END,
+                 t.value COLLATE NOCASE, t.entity_id, t.language, t.term_type, t.ordinal
+               LIMIT 1 OFFSET ?`)
+                        .bind(`%${escaped}%`, filter.language, filter.language, filter.includeDeleted ? 1 : 0, query, candidateOffset)
+                        .all();
+                    const row = hydrated.results[0];
+                    if (!row || row.entity_id !== candidate.entity_id)
+                        throw new AuthorizationDeniedError('Authorization denied');
+                    const after = await this.#readAndAuthorize(candidate.entity_id);
+                    if (before.state.authorizationRevision !==
+                        after.state.authorizationRevision ||
+                        before.record.authorizationRevision !==
+                            after.record.authorizationRevision ||
+                        serializeVisibilityScope(before.record.visibility) !==
+                            serializeVisibilityScope(after.record.visibility))
+                        throw new AuthorizationDeniedError('Authorization denied');
+                    items.push({
+                        entityId: row.entity_id,
+                        entityType: row.entity_type,
+                        language: row.language,
+                        termType: row.term_type,
+                        value: row.value,
+                    });
+                }
+                catch (error) {
+                    if (!(error instanceof AuthorizationDeniedError))
+                        throw error;
+                }
+                offset = candidateOffset + 1;
+                if (items.length === limit) {
+                    if (index < candidates.results.length - 1)
+                        exhausted = false;
+                    break;
+                }
+            }
+            if (!candidates.results.length)
+                exhausted = true;
+        }
+        await this.#reauthorize(items.map((item) => item.entityId));
+        await this.#assertGeneration(generation);
+        return {
+            items,
+            cursor: !exhausted && items.length
+                ? await this.#encodeCursor(binding, generation, { offset })
+                : null,
+        };
+    }
+    async getAuditEvent(eventId) {
+        const candidate = await this.#db
+            .prepare(`SELECT entity_id, revision FROM taproot_audit_events WHERE event_id = ?`)
+            .bind(eventId)
+            .all();
+        const row = candidate.results[0];
+        if (!row)
+            throw new AuthorizationDeniedError('Authorization denied');
+        return this.#authorizedHydration(row.entity_id, row.revision, () => this.#repository.getAuditEvent(eventId));
+    }
+    async listAuditEvents(options = {}) {
+        const limit = authorizedLimit(options.limit, 50);
+        const filter = {
+            entityId: options.entityId ?? null,
+            requestId: options.requestId ?? null,
+            type: options.type ?? null,
+            attributionId: options.attributionId ?? null,
+            tag: options.tag ?? null,
+        };
+        const binding = await this.#binding('audit-events', filter);
+        const generation = await this.#generation();
+        let before = Number.MAX_SAFE_INTEGER;
+        if (options.cursor) {
+            const cursor = await this.#decodeCursor(options.cursor, binding, generation);
+            before = cursorNumber(cursor.position, 'sequence');
+        }
+        await this.#assertContextCurrent();
+        const items = [];
+        let exhausted = false;
+        while (items.length < limit && !exhausted) {
+            const amount = scanLimit(limit - items.length);
+            const candidates = await this.#db
+                .prepare(`SELECT rowid AS sequence, event_id, entity_id, revision FROM taproot_audit_events
+           WHERE (? IS NULL OR entity_id = ?) AND (? IS NULL OR request_id = ?)
+             AND (? IS NULL OR event_type = ?)
+             AND (? IS NULL OR json_extract(attribution_json, '$.id') = ?)
+             AND (? IS NULL OR EXISTS (SELECT 1 FROM json_each(tags_json) WHERE value = ?))
+             AND rowid < ? ORDER BY rowid DESC LIMIT ?`)
+                .bind(filter.entityId, filter.entityId, filter.requestId, filter.requestId, filter.type, filter.type, filter.attributionId, filter.attributionId, filter.tag, filter.tag, before, amount)
+                .all();
+            exhausted = candidates.results.length < amount;
+            for (let index = 0; index < candidates.results.length; index += 1) {
+                const candidate = candidates.results[index];
+                before = candidate.sequence;
+                try {
+                    items.push(await this.#authorizedHydration(candidate.entity_id, candidate.revision, () => this.#repository.getAuditEvent(candidate.event_id)));
+                }
+                catch (error) {
+                    if (!(error instanceof AuthorizationDeniedError))
+                        throw error;
+                }
+                if (items.length === limit) {
+                    if (index < candidates.results.length - 1)
+                        exhausted = false;
+                    break;
+                }
+            }
+            if (!candidates.results.length)
+                exhausted = true;
+        }
+        await this.#reauthorize(items.map((item) => item.entityId));
+        await this.#assertGeneration(generation);
+        return {
+            items,
+            cursor: !exhausted && items.length
+                ? await this.#encodeCursor(binding, generation, { sequence: before })
+                : null,
+        };
+    }
+    async exportEntities(options = {}) {
+        const lines = [];
+        let cursor;
+        do {
+            const page = await this.listEntities({
+                ...options,
+                limit: 100,
+                ...(cursor ? { cursor } : {}),
+            });
+            for (const item of page.items)
+                lines.push(exportEntityJson(item.entity));
+            cursor = page.cursor ?? undefined;
+        } while (cursor);
+        return lines.length ? `${lines.join('\n')}\n` : '';
+    }
+    async inspectEntityIntegrity(id) {
+        requireSearchAdministration(this.#context);
+        return this.#authorizedHydration(id, undefined, () => this.#repository.inspectEntityIntegrity(id));
+    }
+    async inspectTaprootIntegrity(options = {}) {
+        requireSearchAdministration(this.#context);
+        const entities = await this.listEntities({
+            ...options,
+            includeDeleted: true,
+        });
+        const items = [];
+        for (const entity of entities.items)
+            items.push(await this.inspectEntityIntegrity(entity.entityId));
+        return { items, cursor: entities.cursor };
+    }
+    async verifyAuditChain(id) {
+        requireSearchAdministration(this.#context);
+        return this.#authorizedHydration(id, undefined, async () => {
+            const generation = await this.#generation();
+            const revisions = await this.#db
+                .prepare(`SELECT revision FROM taproot_entity_revisions
+           WHERE entity_id = ? ORDER BY revision`)
+                .bind(id)
+                .all();
+            const before = [];
+            for (const { revision } of revisions.results)
+                before.push(await this.#readAndAuthorize(id, revision));
+            const report = await this.#repository.verifyAuditChain(id);
+            for (let index = 0; index < revisions.results.length; index += 1) {
+                const after = await this.#readAndAuthorize(id, revisions.results[index].revision);
+                const prior = before[index];
+                if (prior.state.authorizationRevision !==
+                    after.state.authorizationRevision ||
+                    prior.record.authorizationRevision !==
+                        after.record.authorizationRevision ||
+                    serializeVisibilityScope(prior.record.visibility) !==
+                        serializeVisibilityScope(after.record.visibility))
+                    throw new AuthorizationDeniedError('Authorization denied');
+            }
+            await this.#assertGeneration(generation);
+            return report;
+        });
+    }
+    async repairEntityProjection(id, metadata = {}) {
+        requireSearchAdministration(this.#context);
+        return this.#authorizedHydration(id, undefined, () => this.#repository.repairEntityProjection(id, metadata));
+    }
+    async #binding(operation, filter) {
+        return fingerprintValue({
+            operation,
+            filter,
+            installationId: this.#context.installationId,
+            principalId: this.#context.principalId,
+            activeWorkspaceId: this.#context.activeWorkspaceId,
+            workspaceIds: this.#context.workspaceIds,
+            capabilities: this.#context.capabilities,
+            authorizationRevision: this.#context.authorizationRevision,
+        });
+    }
+    async #generation() {
+        const result = await this.#db
+            .prepare(`SELECT
+           COALESCE((SELECT MAX(rowid) FROM taproot_entity_revisions), 0) AS revision_generation,
+           COALESCE((SELECT MAX(rowid) FROM taproot_audit_events), 0) AS audit_generation,
+           COALESCE((SELECT search_generation FROM taproot_installation_authorization
+                     WHERE singleton = 1), 0) AS search_generation`)
+            .all();
+        const revisionGeneration = Number(result.results[0]?.revision_generation ?? 0);
+        const auditGeneration = Number(result.results[0]?.audit_generation ?? 0);
+        const searchGeneration = Number(result.results[0]?.search_generation ?? 0);
+        if (!Number.isSafeInteger(revisionGeneration) ||
+            revisionGeneration < 0 ||
+            !Number.isSafeInteger(auditGeneration) ||
+            auditGeneration < 0 ||
+            !Number.isSafeInteger(searchGeneration) ||
+            searchGeneration < 1)
+            throw new AuthorizationDeniedError('Authorization denied');
+        return `${revisionGeneration}:${auditGeneration}:${searchGeneration}`;
+    }
+    async #assertGeneration(expected) {
+        if ((await this.#generation()) !== expected)
+            throw new AuthorizationDeniedError('Authorization denied');
+    }
+    async #assertContextCurrent() {
+        try {
+            const state = normalizeInstallationState(await this.#authorization.getInstallationAuthorizationState());
+            if (state.installationId !== this.#context.installationId ||
+                state.authorizationRevision !== this.#context.authorizationRevision)
+                throw new AuthorizationDeniedError('Authorization denied');
+        }
+        catch {
+            throw new AuthorizationDeniedError('Authorization denied');
+        }
+    }
+    async #reauthorize(entityIds) {
+        await this.#assertContextCurrent();
+        for (const entityId of new Set(entityIds))
+            await this.#readAndAuthorize(entityId);
+    }
+    async #encodeCursor(binding, generation, position) {
+        const key = cursorCodecs.get(this.#cursorCodec);
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+        const serialized = new TextEncoder().encode(JSON.stringify({ version: 1, binding, generation, position }));
+        if (serialized.length > CURSOR_PLAINTEXT_BYTES)
+            throw new AuthorizationDeniedError('Authorization denied');
+        const plaintext = new Uint8Array(CURSOR_PLAINTEXT_BYTES);
+        plaintext.fill(0x20);
+        plaintext.set(serialized);
+        const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv, additionalData: CURSOR_AAD }, key, plaintext);
+        return `${base64Url(iv)}.${base64Url(new Uint8Array(encrypted))}`;
+    }
+    async #decodeCursor(encoded, binding, generation) {
+        try {
+            if (encoded.length > 4096)
+                throw new Error('invalid cursor');
+            const parts = encoded.split('.');
+            if (parts.length !== 2)
+                throw new Error('invalid cursor');
+            const key = cursorCodecs.get(this.#cursorCodec);
+            const decrypted = await crypto.subtle.decrypt({
+                name: 'AES-GCM',
+                iv: fromBase64Url(parts[0]).buffer,
+                additionalData: CURSOR_AAD,
+            }, key, fromBase64Url(parts[1]).buffer);
+            const payload = JSON.parse(new TextDecoder().decode(decrypted));
+            if (!isRecord(payload) ||
+                payload.version !== 1 ||
+                payload.binding !== binding ||
+                payload.generation !== generation ||
+                !Object.hasOwn(payload, 'position') ||
+                Object.keys(payload).length !== 4)
+                throw new Error('invalid cursor');
+            return payload;
+        }
+        catch {
+            throw new InvalidCursorError('Cursor is invalid');
+        }
+    }
+    async #authorizedHydration(entityId, revisionNumber, hydrate) {
+        const before = await this.#readAndAuthorize(entityId, revisionNumber);
+        const hydrated = await hydrate();
+        const after = await this.#readAndAuthorize(entityId, revisionNumber);
+        if (before.state.authorizationRevision !==
+            after.state.authorizationRevision ||
+            before.record.authorizationRevision !==
+                after.record.authorizationRevision ||
+            serializeVisibilityScope(before.record.visibility) !==
+                serializeVisibilityScope(after.record.visibility))
+            throw new AuthorizationDeniedError('Authorization denied');
+        return hydrated;
+    }
+    async #readAndAuthorize(entityId, revisionNumber) {
+        let state;
+        let record;
+        try {
+            [state, record] = await Promise.all([
+                this.#authorization.getInstallationAuthorizationState(),
+                this.#authorization.getEntityAuthorization(entityId),
+            ]);
+            const normalizedState = normalizeInstallationState(state);
+            const current = normalizeAuthorizationRecord(record);
+            if (normalizedState.installationId !== this.#context.installationId ||
+                current.installationId !== this.#context.installationId ||
+                normalizedState.authorizationRevision !==
+                    this.#context.authorizationRevision ||
+                current.authorizationRevision > normalizedState.authorizationRevision ||
+                !isVisibleTo(current.visibility, this.#context))
+                throw new AuthorizationDeniedError('Authorization denied');
+            let effective = current;
+            if (revisionNumber !== undefined) {
+                const historical = normalizeAuthorizationRecord(await this.#authorization.getEntityRevisionAuthorization(entityId, revisionNumber));
+                if (historical.installationId !== current.installationId)
+                    throw new AuthorizationDeniedError('Authorization denied');
+                effective = {
+                    ...current,
+                    authorizationRevision: Math.max(current.authorizationRevision, historical.authorizationRevision),
+                    visibility: intersectVisibilityScopes(current.visibility, historical.visibility),
+                };
+            }
+            if (effective.authorizationRevision >
+                normalizedState.authorizationRevision ||
+                !isVisibleTo(effective.visibility, this.#context))
+                throw new AuthorizationDeniedError('Authorization denied');
+            return { state: normalizedState, record: effective };
+        }
+        catch {
+            throw new AuthorizationDeniedError('Authorization denied');
+        }
+    }
+}
+/** Taproot-owned, fail-closed canonical policy source. */
+export class PersistedEntityAuthorizationSource {
+    #db;
+    constructor(db) {
+        this.#db = db;
+    }
+    async getInstallationAuthorizationState() {
+        const result = await this.#db
+            .prepare(`SELECT installation_id, authorization_revision, search_generation
+         FROM taproot_installation_authorization WHERE singleton = 1`)
+            .all();
+        const row = result.results[0];
+        if (!row)
+            throw new AuthorizationDeniedError('Authorization denied');
+        return {
+            installationId: row.installation_id,
+            authorizationRevision: Number(row.authorization_revision),
+            searchGeneration: Number(row.search_generation),
+        };
+    }
+    async getEntityAuthorization(entityId) {
+        const result = await this.#db
+            .prepare(`SELECT p.installation_id, p.authorization_revision,
+                p.effective_visibility_json AS visibility_json,
+                p.visibility_json AS declared_visibility_json,
+                p.workspace_id, p.owner_principal_id, p.source_revision
+         FROM taproot_entity_authorization p
+         JOIN taproot_entity_authorization_revisions history
+           ON history.entity_id = p.entity_id
+          AND history.source_revision = p.source_revision
+          AND history.installation_id IS p.installation_id
+          AND history.workspace_id IS p.workspace_id
+          AND history.owner_principal_id IS p.owner_principal_id
+          AND history.visibility_json IS p.visibility_json
+          AND history.effective_visibility_json IS p.effective_visibility_json
+          AND history.authorization_revision IS p.authorization_revision
+          AND history.deleted_at IS p.deleted_at
+          AND history.event_id IS p.event_id
+          AND history.created_at IS p.updated_at
+         JOIN taproot_entities e ON e.entity_id = p.entity_id
+           AND e.revision = p.source_revision
+         JOIN taproot_installation_authorization state ON state.singleton = 1
+           AND state.installation_id = p.installation_id
+           AND p.authorization_revision BETWEEN 1 AND state.authorization_revision
+         WHERE p.entity_id = ? AND p.deleted_at IS NULL
+           AND e.deleted_at IS NULL`)
+            .bind(entityId)
+            .all();
+        const row = result.results[0];
+        if (!row)
+            return null;
+        const declared = parseCanonicalVisibilityScope(row.declared_visibility_json);
+        const effective = parseCanonicalVisibilityScope(row.visibility_json);
+        if (!declared || !effective)
+            return null;
+        const statements = await this.#db
+            .prepare(`SELECT taproot_statement_authorization.restrictions_json,
+                taproot_statement_authorization.effective_visibility_json,
+                taproot_statement_authorization.authorization_revision
+         FROM taproot_statement_authorization
+         JOIN taproot_statement_authorization_revisions history
+           ON history.entity_id = taproot_statement_authorization.entity_id
+          AND history.source_revision = taproot_statement_authorization.source_revision
+          AND history.statement_id = taproot_statement_authorization.statement_id
+          AND history.restrictions_json IS taproot_statement_authorization.restrictions_json
+          AND history.effective_visibility_json IS taproot_statement_authorization.effective_visibility_json
+          AND history.authorization_revision IS taproot_statement_authorization.authorization_revision
+         WHERE taproot_statement_authorization.entity_id = ?
+           AND taproot_statement_authorization.source_revision = ?
+         ORDER BY taproot_statement_authorization.statement_id`)
+            .bind(entityId, row.source_revision)
+            .all();
+        let expectedEffective = declared;
+        for (const statement of statements.results) {
+            const restrictions = parseCanonicalVisibilityRestrictions(statement.restrictions_json);
+            const statementEffective = parseCanonicalVisibilityScope(statement.effective_visibility_json);
+            if (!restrictions ||
+                !statementEffective ||
+                Number(statement.authorization_revision) !==
+                    Number(row.authorization_revision))
+                return null;
+            const expectedStatement = intersectVisibilityScopes(declared, ...restrictions);
+            if (serializeVisibilityScope(statementEffective) !==
+                serializeVisibilityScope(expectedStatement))
+                return null;
+            expectedEffective = intersectVisibilityScopes(expectedEffective, expectedStatement);
+        }
+        if (serializeVisibilityScope(effective) !==
+            serializeVisibilityScope(expectedEffective))
+            return null;
+        return authorizationRecordFromRow(row);
+    }
+    async getEntityRevisionAuthorization(entityId, revisionNumber) {
+        const current = await this.getEntityAuthorization(entityId);
+        if (!current)
+            return null;
+        const result = await this.#db
+            .prepare(`SELECT history.installation_id, history.authorization_revision,
+                history.effective_visibility_json AS historical_visibility_json,
+                history.visibility_json AS historical_declared_visibility_json,
+                history.workspace_id, history.owner_principal_id,
+                history.source_revision
+         FROM taproot_entity_authorization_revisions history
+         JOIN taproot_installation_authorization state ON state.singleton = 1
+           AND state.installation_id = history.installation_id
+           AND history.authorization_revision BETWEEN 1 AND state.authorization_revision
+         WHERE history.entity_id = ? AND history.source_revision = ?
+           AND history.deleted_at IS NULL`)
+            .bind(entityId, revisionNumber)
+            .all();
+        const row = result.results[0];
+        if (!row || row.installation_id !== current.installationId)
+            return null;
+        const declared = parseCanonicalVisibilityScope(row.historical_declared_visibility_json);
+        const effective = parseCanonicalVisibilityScope(row.historical_visibility_json);
+        if (!declared || !effective)
+            return null;
+        const coverage = await this.#db
+            .prepare(`WITH expected(statement_id) AS (
+           SELECT json_extract(statement.value, '$.id')
+           FROM taproot_entity_revisions revision,
+             json_each(revision.entity_json, '$.claims') claim,
+             json_each(claim.value) statement
+           WHERE revision.entity_id = ? AND revision.revision = ?
+         )
+         SELECT
+           (SELECT COUNT(*) FROM expected) AS expected_count,
+           (SELECT COUNT(*) FROM taproot_statement_authorization_revisions policy
+             WHERE policy.entity_id = ? AND policy.source_revision = ?) AS actual_count,
+           (SELECT COUNT(*) FROM expected WHERE NOT EXISTS (
+             SELECT 1 FROM taproot_statement_authorization_revisions policy
+             WHERE policy.entity_id = ? AND policy.source_revision = ?
+               AND policy.statement_id = expected.statement_id
+           )) AS missing_count`)
+            .bind(entityId, revisionNumber, entityId, revisionNumber, entityId, revisionNumber)
+            .all();
+        const coverageRow = coverage.results[0];
+        if (!coverageRow ||
+            Number(coverageRow.expected_count) !== Number(coverageRow.actual_count) ||
+            Number(coverageRow.missing_count) !== 0)
+            return null;
+        const statements = await this.#db
+            .prepare(`SELECT restrictions_json, effective_visibility_json,
+                authorization_revision
+         FROM taproot_statement_authorization_revisions
+         WHERE entity_id = ? AND source_revision = ?
+         ORDER BY statement_id`)
+            .bind(entityId, revisionNumber)
+            .all();
+        let expectedEffective = declared;
+        for (const statement of statements.results) {
+            const restrictions = parseCanonicalVisibilityRestrictions(statement.restrictions_json);
+            const statementEffective = parseCanonicalVisibilityScope(statement.effective_visibility_json);
+            if (!restrictions ||
+                !statementEffective ||
+                Number(statement.authorization_revision) !==
+                    Number(row.authorization_revision))
+                return null;
+            const expectedStatement = intersectVisibilityScopes(declared, ...restrictions);
+            if (serializeVisibilityScope(statementEffective) !==
+                serializeVisibilityScope(expectedStatement))
+                return null;
+            expectedEffective = intersectVisibilityScopes(expectedEffective, expectedStatement);
+        }
+        if (serializeVisibilityScope(effective) !==
+            serializeVisibilityScope(expectedEffective))
+            return null;
+        return {
+            installationId: row.installation_id,
+            authorizationRevision: Math.max(current.authorizationRevision, Number(row.authorization_revision)),
+            visibility: intersectVisibilityScopes(current.visibility, effective),
+            workspaceId: row.workspace_id,
+            ownerPrincipalId: row.owner_principal_id,
+            sourceRevision: Number(row.source_revision),
+        };
+    }
+    async getStatementAuthorization(entityId, statementId) {
+        const result = await this.#db
+            .prepare(`SELECT p.installation_id, s.authorization_revision,
+                s.effective_visibility_json AS visibility_json,
+                s.restrictions_json, p.visibility_json AS parent_visibility_json,
+                p.effective_visibility_json AS parent_effective_visibility_json,
+                p.authorization_revision AS parent_authorization_revision,
+                p.workspace_id, p.owner_principal_id, s.source_revision
+         FROM taproot_statement_authorization s
+         JOIN taproot_statement_authorization_revisions history
+           ON history.entity_id = s.entity_id
+          AND history.source_revision = s.source_revision
+          AND history.statement_id = s.statement_id
+          AND history.restrictions_json IS s.restrictions_json
+          AND history.effective_visibility_json IS s.effective_visibility_json
+          AND history.authorization_revision IS s.authorization_revision
+         JOIN taproot_entity_authorization p ON p.entity_id = s.entity_id
+            AND p.source_revision = s.source_revision
+         JOIN taproot_entity_authorization_revisions parent_history
+           ON parent_history.entity_id = p.entity_id
+          AND parent_history.source_revision = p.source_revision
+          AND parent_history.installation_id IS p.installation_id
+          AND parent_history.workspace_id IS p.workspace_id
+          AND parent_history.owner_principal_id IS p.owner_principal_id
+          AND parent_history.visibility_json IS p.visibility_json
+          AND parent_history.effective_visibility_json IS p.effective_visibility_json
+          AND parent_history.authorization_revision IS p.authorization_revision
+          AND parent_history.deleted_at IS p.deleted_at
+          AND parent_history.event_id IS p.event_id
+          AND parent_history.created_at IS p.updated_at
+         JOIN taproot_entities e ON e.entity_id = s.entity_id
+            AND e.revision = s.source_revision
+         JOIN taproot_installation_authorization state ON state.singleton = 1
+           AND state.installation_id = p.installation_id
+           AND p.authorization_revision BETWEEN 1 AND state.authorization_revision
+           AND s.authorization_revision BETWEEN 1 AND state.authorization_revision
+         WHERE s.entity_id = ? AND s.statement_id = ?
+           AND p.deleted_at IS NULL AND e.deleted_at IS NULL`)
+            .bind(entityId, statementId)
+            .all();
+        const row = result.results[0];
+        if (!row ||
+            Number(row.authorization_revision) !==
+                Number(row.parent_authorization_revision))
+            return null;
+        const declaredParent = parseCanonicalVisibilityScope(row.parent_visibility_json);
+        const restrictions = parseCanonicalVisibilityRestrictions(row.restrictions_json);
+        const effective = parseCanonicalVisibilityScope(row.visibility_json);
+        if (!declaredParent ||
+            !restrictions ||
+            !effective ||
+            serializeVisibilityScope(effective) !==
+                serializeVisibilityScope(intersectVisibilityScopes(declaredParent, ...restrictions)))
+            return null;
+        return authorizationRecordFromRow(row);
+    }
+}
+function parseCanonicalVisibilityRestrictions(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (!Array.isArray(value))
+            return null;
+        const restrictions = value.map((scope) => normalizeVisibilityScope(scope));
+        return JSON.stringify(restrictions) === raw ? restrictions : null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseCanonicalVisibilityScope(raw) {
+    try {
+        const scope = normalizeVisibilityScope(JSON.parse(raw));
+        return serializeVisibilityScope(scope) === raw ? scope : null;
+    }
+    catch {
+        return null;
+    }
+}
+function authorizationRecordFromRow(row) {
+    if (!row)
+        return null;
+    return {
+        installationId: row.installation_id,
+        authorizationRevision: Number(row.authorization_revision),
+        visibility: JSON.parse(row.visibility_json),
+        workspaceId: row.workspace_id,
+        ownerPrincipalId: row.owner_principal_id,
+        sourceRevision: Number(row.source_revision),
+    };
+}
+export function createAuthorizedTaproot(db, options, context, authorizedOptions) {
+    return new AuthorizedTaprootReader(db, options, context, authorizedOptions);
+}
+function normalizeInstallationState(value) {
+    if (!isRecord(value))
+        invalid('authorization state must be an object');
+    exactKeys(value, [
+        'installationId',
+        'authorizationRevision',
+        'searchGeneration',
+    ]);
+    return {
+        installationId: identifier(value.installationId, 'installationId'),
+        authorizationRevision: revision(value.authorizationRevision, 'authorizationRevision'),
+        searchGeneration: revision(value.searchGeneration, 'searchGeneration'),
+    };
+}
+function normalizeAuthorizationRecord(value) {
+    if (!isRecord(value))
+        invalid('authorization record must be an object');
+    exactKeys(value, [
+        'installationId',
+        'authorizationRevision',
+        'visibility',
+        'workspaceId',
+        'ownerPrincipalId',
+        'sourceRevision',
+    ]);
+    return {
+        installationId: identifier(value.installationId, 'installationId'),
+        authorizationRevision: revision(value.authorizationRevision, 'authorizationRevision'),
+        visibility: normalizeVisibilityScope(value.visibility),
+        workspaceId: value.workspaceId === null
+            ? null
+            : identifier(value.workspaceId, 'workspaceId'),
+        ownerPrincipalId: identifier(value.ownerPrincipalId, 'ownerPrincipalId'),
+        sourceRevision: revision(value.sourceRevision, 'sourceRevision'),
+    };
+}
+function normalizeAtom(value) {
+    if (!isRecord(value) || typeof value.kind !== 'string')
+        invalid('visibility atom must be an object');
+    switch (value.kind) {
+        case 'public':
+            if (Object.keys(value).length !== 1)
+                invalid('public atom has unknown fields');
+            return { kind: 'public' };
+        case 'principal':
+            exactKeys(value, ['kind', 'principalId']);
+            return {
+                kind: 'principal',
+                principalId: identifier(value.principalId, 'principalId'),
+            };
+        case 'workspace':
+            exactKeys(value, ['kind', 'workspaceId']);
+            return {
+                kind: 'workspace',
+                workspaceId: identifier(value.workspaceId, 'workspaceId'),
+            };
+        case 'capability':
+            exactKeys(value, ['kind', 'capability']);
+            return {
+                kind: 'capability',
+                capability: identifier(value.capability, 'capability'),
+            };
+        default:
+            invalid('visibility atom kind is not supported');
+    }
+}
+function serializeAtom(atom) {
+    return JSON.stringify(atom);
+}
+function stringSet(value, field) {
+    if (!Array.isArray(value) || value.length > 256)
+        invalid(`${field} must be an array with at most 256 entries`);
+    const normalized = [];
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index))
+            invalid(`${field} must be dense`);
+        normalized.push(identifier(value[index], field));
+    }
+    return [...new Set(normalized)].sort(compareCodeUnits);
+}
+function identifier(value, field) {
+    if (typeof value !== 'string')
+        invalid(`${field} must be a string`);
+    const normalized = value.normalize('NFC');
+    if (normalized.length === 0 ||
+        normalized.length > MAX_IDENTIFIER_LENGTH ||
+        normalized.trim() !== normalized ||
+        hasControlCharacter(normalized))
+        invalid(`${field} is invalid`);
+    return normalized;
+}
+function revision(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        invalid(`${field} must be a non-negative safe integer`);
+    return value;
+}
+function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    if (actual.length !== wanted.length ||
+        actual.some((key, index) => key !== wanted[index]))
+        invalid('visibility atom has unknown or missing fields');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function hasControlCharacter(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint <= 0x1f || codePoint === 0x7f)
+            return true;
+    }
+    return false;
+}
+function authorizedLimit(value, fallback) {
+    const limit = value ?? fallback;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500)
+        throw new RangeError('limit must be an integer from 1 through 500');
+    return limit;
+}
+function scanLimit(remaining) {
+    return Math.min(500, Math.max(32, remaining * 4));
+}
+function cursorNumber(position, key) {
+    if (!isRecord(position) ||
+        Object.keys(position).length !== 1 ||
+        !Object.hasOwn(position, key))
+        throw new InvalidCursorError('Cursor is invalid');
+    const value = position[key];
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new InvalidCursorError('Cursor is invalid');
+    return value;
+}
+function entityPosition(position) {
+    if (!isRecord(position))
+        throw new InvalidCursorError('Cursor is invalid');
+    exactKeys(position, ['entityType', 'numericId']);
+    if ((position.entityType !== 'item' && position.entityType !== 'property') ||
+        !Number.isSafeInteger(position.numericId) ||
+        position.numericId < 0)
+        throw new InvalidCursorError('Cursor is invalid');
+    return {
+        entityType: position.entityType,
+        numericId: position.numericId,
+    };
+}
+async function fingerprintValue(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return base64Url(new Uint8Array(digest));
+}
+function base64Url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary)
+        .replaceAll('+', '-')
+        .replaceAll('/', '_')
+        .replace(/=+$/u, '');
+}
+function fromBase64Url(value) {
+    if (!/^[A-Za-z0-9_-]+$/u.test(value))
+        throw new Error('invalid base64url');
+    const padding = '='.repeat((4 - (value.length % 4)) % 4);
+    const binary = atob(value.replaceAll('-', '+').replaceAll('_', '/') + padding);
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    if (base64Url(bytes) !== value)
+        throw new Error('invalid base64url');
+    return bytes;
+}
+function invalid(message) {
+    throw new InvalidAuthorizationError(message);
+}
+//# sourceMappingURL=authorization.js.map