@haverstack/core 0.40.0 → 0.42.0

package/dist/scoped-stack/scoped-stack.js

@@ -0,0 +1,776 @@
+/**
+ * ScopedStack — the permission-enforcing view
+ * -------------------------------------------------------
+ * A `Stack` answers every question; a `ScopedStack` answers only the ones a
+ * particular requester is entitled to. It wraps a Stack rather than an
+ * adapter, so every invariant the Stack layer holds is already in force by
+ * the time a check here runs, and the gates below only ever narrow.
+ *
+ * Two identities, one rule: **the principal governs authority, the subject
+ * governs attribution.** Both are DIDs and both are often equal, which is
+ * what makes them easy to confuse — so the split is stated on every gate
+ * that depends on it. Grant lookup and the privilege-bearing gates no grant
+ * reaches (resharing, group management, purge, widening access at create
+ * time) key on the principal; authorship, `-own` matching, record-level
+ * permissions and "files I uploaded" key on the subject. Unconditional
+ * owner access splits the same way: an owner subject passes every
+ * permission check, an owner principal is not bounded by grants, and under
+ * delegation both halves apply. The questions those gates ask are
+ * ScopeAuthority's, in authority.ts; this module turns their answers into
+ * refusals.
+ *
+ * Also holds the feed side of the same rule: a subscription's deliveries
+ * run through the same canRead() a get() answers with, so a feed can never
+ * disagree with a read about what a session sees.
+ *
+ * See docs/spec/access-control.md and docs/spec/events.md § Permission scoping.
+ */
+import { baseIdOf } from '../schema.js';
+import { validatePatchValues } from '../validate.js';
+import { ChangeEmitter, assertSinceUsable } from '../stack/changes.js';
+import { SYSTEM_TYPES } from '../types/index.js';
+import { StackConflictError, StackNotFoundError, StackPermissionError, RelayScopeError, StackValidationError, } from '../errors.js';
+import { assertAssociationEdits, assertAssociationList, assertAuthorityAssociations, assertDataAssociations, } from '../associations/validation.js';
+import { associationDelta, associationEqual, editsOf } from '../associations/identity.js';
+import { isGroupRecord } from '../access.js';
+import { assertSortCapability, assertValidAssociationFilters, assertValidBaseIdFilter, assertValidSort, filtersContent, } from '../query-validation.js';
+import { bindingFieldsOf } from '../stack/identity-bindings.js';
+import { checkFamily, storedVersionDiffers, WRITE_EXPECTATION, } from '../stack/write-expectation.js';
+import { assertAttachmentSize } from '../stack/limits.js';
+import { validateIdTimestampSkew, validateRecordId } from '../stack/record-id.js';
+import { DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, findAppCardByDid, lookupEntityByDid, } from '../stack/reads.js';
+import { assertNonEmptyChangeSet, presentDeleted, withoutAuthorityChanges, } from '../record-changes.js';
+import { createCollection } from '../collection.js';
+import { uploadContent } from '../stack/attachments.js';
+import { ScopeAuthority } from './authority.js';
+import { ScopedSubscription } from './subscription.js';
+/**
+ * Held by Stack alone: the index re-exports ScopedStack but not this, so
+ * asEntity()/asActor() stay the only way to one, and the actor
+ * normalization and open-check they run can't be skipped.
+ */
+export const scopeToken = Symbol('ScopedStack');
+/**
+ * A permission-enforcing view of a Stack for one (principal, subject) pair,
+ * obtained via `stack.asEntity()` or `stack.asActor()`. A record the request
+ * cannot read answers exactly as a missing one does.
+ * See docs/spec/disclosure.md § Which refusal a Record answers with.
+ */
+export class ScopedStack {
+    #authority;
+    stack;
+    idTimestampSkewMs;
+    adapter;
+    changes;
+    assertStackOpen;
+    relaysChanges;
+    migrations;
+    /** Not callable from outside the package — see ScopedStackInit. */
+    constructor(token, init) {
+        if (token !== scopeToken) {
+            throw new TypeError('A ScopedStack is obtained through Stack.asEntity() or Stack.asActor()');
+        }
+        this.stack = init.stack;
+        this.#authority = new ScopeAuthority(init.stack, init.principalId, init.subjectId);
+        this.idTimestampSkewMs = init.idTimestampSkewMs;
+        this.adapter = init.adapter;
+        this.changes = init.changes;
+        this.assertStackOpen = init.assertOpen;
+        this.relaysChanges = init.relaysChanges;
+        this.migrations = init.migrations;
+    }
+    collection(handle) {
+        this.assertStackOpen();
+        return createCollection(this, this.migrations, handle, () => this.stack.listTypes());
+    }
+    /**
+     * The identity whose authority this view acts with; `null` when
+     * anonymous. See docs/spec/access-control.md § Delegation: principal and subject.
+     */
+    get principalId() {
+        return this.#authority.principalId;
+    }
+    /**
+     * The identity this view acts for and attributes writes to; `null` when
+     * anonymous. Equal to `principalId` unless an app is acting for a user.
+     */
+    get subjectId() {
+        return this.#authority.subjectId;
+    }
+    get capabilities() {
+        return this.stack.capabilities;
+    }
+    get actor() {
+        // The key is always present, so spreading this last overrides anything
+        // a caller passed: a scoped requester names itself by making the
+        // request, never by describing itself in the options.
+        return { actor: this.#authority.requester };
+    }
+    /** Refuse a create this request holds no grant for — see ScopeAuthority.checkCreateGrant(). */
+    async requireCreateGrant(typeId) {
+        if (!(await this.#authority.checkCreateGrant(typeId))) {
+            throw new StackPermissionError(`No create grant for type "${typeId}"`);
+        }
+    }
+    /** Refuse anything but the owner acting as itself — see ScopeAuthority.ownerActingAlone. */
+    requireOwnerActingAlone(message) {
+        if (!this.#authority.ownerActingAlone)
+            throw new StackPermissionError(message);
+    }
+    /**
+     * Fetch a record the subject can reach and the principal holds `update` on
+     * (via permissions or an update grant), or throw. `mutating: false` marks
+     * the history readers, which borrow this gate without changing anything —
+     * the one way through it a `_grant` Record stays open to.
+     */
+    async requireUpdatable(id, opts = {}) {
+        // The `_grant` write fence applies to mutating callers only: reading a
+        // grant Record's history is not the escalation that fence exists to stop.
+        return this.requireVerb(id, ['update-own', 'update-any'], {
+            fenceGrantRecord: opts.mutating ?? true,
+            expect: opts.expect,
+        });
+    }
+    /**
+     * The write gate both requireUpdatable() and requireDeletable() are: the
+     * subject can reach the record (record-level permission or a grant) and
+     * the principal holds the same verb, intersected — or, for a `_group`, the
+     * stricter management rule that no grant reaches.
+     * See docs/spec/access-control.md § Delegation: principal and subject.
+     */
+    async requireVerb(id, actions, opts) {
+        const record = await this.stack.get(id, { includeDeleted: true });
+        if (!record)
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        // Ahead of the gate, so another family's record is not found whatever
+        // this requester may do to it — the answer a collection's get() gives.
+        checkFamily(record, opts.expect);
+        if (opts.fenceGrantRecord)
+            await this.requireOwnerForGrantRecord(record);
+        if (isGroupRecord(record)) {
+            if (!this.#authority.isGroupManager(record)) {
+                throw await this.#authority.denialFor(record, `Cannot change group "${id}": only its admins can manage it`);
+            }
+            return record;
+        }
+        const subjectReaches = (await this.#authority.recordPermits(record, 'write')) ||
+            (await this.#authority.subjectAllows(record.typeId, actions, { record }));
+        const principalHolds = await this.#authority.principalAllows(record.typeId, actions);
+        if (!subjectReaches || !principalHolds) {
+            const verb = actions[0].split('-')[0];
+            const what = `Cannot ${verb} "${id}" (${record.typeId})`;
+            throw await this.#authority.denialFor(record, subjectReaches
+                ? `${what}: the app acting for this entity holds no ${verb} grant`
+                : `${what}: requires ${actions.join(' or ')}`);
+        }
+        return record;
+    }
+    /**
+     * Fetch a record the subject can reach and the principal holds `delete` on
+     * (via permissions or a delete grant), or throw.
+     */
+    requireDeletable(id, expect) {
+        // No soft-delete refusal: undelete() shares this gate, and a tombstone
+        // is exactly what it addresses.
+        return this.requireVerb(id, ['delete-own', 'delete-any'], { fenceGrantRecord: true, expect });
+    }
+    /**
+     * Gates file-ref content fields on file access, mirroring the
+     * attachment-association gate — a file-ref field conveys attachment
+     * access exactly like an `attachment` association. Only fields present
+     * in `content` are checked (a content patch is a merge patch; untouched fields
+     * carry no new reference).
+     */
+    async requireFileRefAccess(typeId, content) {
+        for (const field of await this.#authority.fileRefFieldNames(typeId)) {
+            const value = content[field];
+            if (typeof value !== 'string')
+                continue;
+            if (!(await this.#authority.canAccessFile(value))) {
+                throw new StackPermissionError(`Cannot reference file "${value}" in field "${field}": it does not exist or you cannot read it`);
+            }
+        }
+    }
+    /**
+     * Reference-creation gate for one association: file access for an
+     * `attachment`, read access for a `relationship` to a record in this
+     * stack. Other targets convey nothing, and a `_group` roster has the
+     * stricter management gate. See docs/spec/access-control.md
+     * § Reference-creation gating.
+     */
+    async requireAssociationAccess(typeId, association) {
+        if (association.kind === 'attachment') {
+            if (!(await this.#authority.canAccessFile(association.fileId))) {
+                throw new StackPermissionError(`Cannot reference file "${association.fileId}": it does not exist or you cannot read it`);
+            }
+        }
+        else if (association.kind === 'relationship' && baseIdOf(typeId) !== SYSTEM_TYPES.GROUP) {
+            const { target } = association;
+            // `stackUrl` is tested for a value, not for presence: absent and
+            // empty are one target — storage, targetEqual() and the filter all
+            // read them as this stack — so a check on presence alone would
+            // leave one spelling of a local Record ungated.
+            if (target.kind !== 'record' || target.stackUrl)
+                return;
+            if (!(await this.#authority.canReadReferent(target.recordId))) {
+                throw new StackPermissionError(`Cannot reference record "${target.recordId}": it does not exist or you cannot read it`);
+            }
+        }
+    }
+    /**
+     * Create a record on behalf of the subject, stamped with the requester as
+     * `createdBy`. Every option that could widen reach or forge a position is
+     * refused rather than dropped, so an app never believes it published
+     * something it didn't. See docs/spec/data-model.md § Backdating on import.
+     */
+    async create(typeId, content, opts = {}) {
+        const principal = this.#authority.principalId;
+        if (!principal)
+            throw new StackPermissionError('Anonymous requesters cannot create records');
+        // A grantee is exactly the untrusted actor the `id` skew check below
+        // exists to stop from forging a sort position, and a delegated app
+        // acting for the owner inherits none of the owner's extra trust — same
+        // reasoning as ScopeAuthority.mayGrantAccess(). Asked value-wise, since an
+        // `undefined` carries no date and Stack.create() reads it as absent.
+        if ((opts.createdAt !== undefined || opts.updatedAt !== undefined) &&
+            !this.#authority.ownerActingAlone) {
+            throw new StackPermissionError('createdAt/updatedAt can only be set by the stack owner acting alone; a grantee or delegated create always stamps the current time.');
+        }
+        await this.requireCreateGrant(typeId);
+        // The exemption is the owner's own, so delegation doesn't carry it: an
+        // owner principal acting for someone else would otherwise let that
+        // subject name any fileId and reach the bytes through the uploader
+        // clause, which matches on the subject this create stamps.
+        if (!this.#authority.ownerActingAlone && baseIdOf(typeId) === SYSTEM_TYPES.ATTACHMENT) {
+            const fileId = content.fileId;
+            if (typeof fileId !== 'string' || !(await this.#authority.hasReadableReference(fileId))) {
+                throw new StackPermissionError(`Cannot reference file "${String(fileId)}": it does not exist or you cannot read it`);
+            }
+        }
+        if (opts.permissions?.length && !this.#authority.mayGrantAccess()) {
+            throw new StackPermissionError('A delegated principal cannot set permissions, at create time or after');
+        }
+        if (opts.unlisted && !this.#authority.mayGrantAccess()) {
+            throw new StackPermissionError('A delegated principal cannot create an unlisted record, at create time or after');
+        }
+        this.requireOwnerForOwnerDid(typeId, content.did);
+        await this.requireAppIdMatchesPrincipal(opts.appId);
+        if (opts.id !== undefined) {
+            validateRecordId(opts.id);
+            // A backdated create — the owner's alone, checked above — has its id
+            // checked against `createdAt` by Stack.create() instead of against now.
+            // See docs/spec/data-model.md § Record IDs.
+            if (opts.createdAt === undefined) {
+                validateIdTimestampSkew(opts.id, this.idTimestampSkewMs, Date.now(), 'the current time');
+            }
+        }
+        if (opts.parentId !== undefined && !(await this.#authority.canReadReferent(opts.parentId))) {
+            throw new StackPermissionError(`Cannot reference record "${opts.parentId}" as parent: it does not exist or you cannot read it`);
+        }
+        for (const assoc of opts.associations ?? []) {
+            await this.requireAssociationAccess(typeId, assoc);
+        }
+        await this.requireFileRefAccess(typeId, content);
+        return this.stack.create(typeId, content, {
+            ...opts,
+            createdBy: this.#authority.requester,
+        });
+    }
+    /**
+     * A record this request may read, or null. Never throws
+     * StackPermissionError: an unreadable record answers exactly as a missing
+     * one does, so a caller learns only what it may read.
+     * See docs/spec/disclosure.md § Which refusal a Record answers with.
+     */
+    async get(id, opts = {}) {
+        const record = await this.stack.get(id, opts);
+        if (!record)
+            return null;
+        if (!(await this.#authority.canRead(record)))
+            return null;
+        return presentDeleted(record);
+    }
+    /**
+     * Runs through this.query(), so canRead() still applies — this answers a
+     * question the caller asks on its own behalf. includeUnlisted is passed
+     * only when the request is the owner acting alone, per
+     * docs/spec/identity.md § DID bindings.
+     */
+    async getEntityByDid(did) {
+        return lookupEntityByDid((q) => this.query(q), did, filtersContent(this.stack.capabilities), this.#authority.ownerActingAlone);
+    }
+    async getOwnerEntity() {
+        return this.getEntityByDid(this.stack.ownerEntityId);
+    }
+    /**
+     * Query records, filtered to those this request can read. Pages are
+     * filtered then refilled, so a page may slightly overshoot `limit` but
+     * never skips a record. Grants are prefetched once, cursor-walked to
+     * exhaustion.
+     */
+    async query(query = {}) {
+        assertValidSort(query.sort);
+        assertSortCapability(query.sort, this.stack.capabilities);
+        assertValidAssociationFilters(query.filter);
+        assertValidBaseIdFilter(query.filter);
+        if (query.filter?.includeUnlisted && !this.#authority.ownerActingAlone) {
+            throw new StackPermissionError('includeUnlisted is owner-only');
+        }
+        const limit = Math.min(query.limit ?? DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT);
+        const records = [];
+        const maxFetched = limit * 10;
+        let totalFetched = 0;
+        const prefetchedGrants = this.#authority.identified
+            ? await this.#authority.loadGrants()
+            : undefined;
+        // Scoped to this query, like prefetchedGrants beside it: every
+        // candidate Record shares one roster resolution per group, and nothing
+        // is carried into the next operation.
+        const groupRoles = new Map();
+        let page = { records: [], cursor: query.cursor ?? null };
+        do {
+            page = await this.stack.query({ ...query, cursor: page.cursor ?? undefined });
+            totalFetched += page.records.length;
+            for (const record of page.records) {
+                // Projected here as well as in get(), or `includeDeleted` would be
+                // a strictly better read channel than the fetch-by-ID it is
+                // supposed to match.
+                if (await this.#authority.canRead(record, prefetchedGrants, groupRoles)) {
+                    records.push(presentDeleted(record));
+                }
+            }
+        } while (records.length < limit && page.cursor && totalFetched < maxFetched);
+        return { records, cursor: page.cursor };
+    }
+    /**
+     * Apply a change set on behalf of the subject. Each key is gated against
+     * the record as it stands, never as the set would leave it, and one
+     * refused key refuses the call. See docs/spec/access-control.md
+     * § Composing a change set.
+     */
+    async mutate(id, changes, opts = {}) {
+        // Ahead of every gate: a malformed change set is a validation error
+        // for every requester, rather than one for the owner and a permission
+        // refusal for everyone else.
+        assertNonEmptyChangeSet(changes);
+        if (changes.contentPatch) {
+            const patchErrors = validatePatchValues(changes.contentPatch);
+            if (patchErrors.length > 0)
+                throw new StackValidationError(patchErrors);
+        }
+        // Refused here as well as in `Stack` below, so the partition is a
+        // refusal rather than a permission question: an `associations` key
+        // naming an authority kind is the wrong surface for every requester,
+        // owner included.
+        if (changes.associations)
+            assertDataAssociations(changes.associations, 'associations');
+        if (changes.permissions)
+            assertAuthorityAssociations(changes.permissions, 'permissions');
+        const writes = changes.contentPatch !== undefined ||
+            changes.associations !== undefined ||
+            changes.parentId !== undefined;
+        // `unlisted` reshares on presence alone; a restated `permissions` set
+        // does not, which permissionsMove() decides once the record is in hand.
+        // See docs/spec/access-control.md § Storage unifies; the API does not.
+        const unlists = changes.unlisted !== undefined;
+        // requireUpdatable() reads the record and applies the write gate; the
+        // reshare keys need the record before their own gate, and a change set
+        // carrying only those must not be held to the write gate it doesn't
+        // need. One read either way.
+        const record = writes
+            ? await this.requireUpdatable(id, { expect: opts })
+            : await this.requireReshareable(id, opts);
+        // A key the gate read as inert is dropped, not forwarded: `Stack`
+        // recomputes the delta from its own read, and must not write an ACL on
+        // the strength of this one. See docs/spec/access-control.md
+        // § Storage unifies; the API does not.
+        let authorized = changes;
+        if (writes) {
+            const moves = this.permissionsMove(record, changes);
+            if (unlists || moves)
+                await this.requireReshareOf(record);
+            if (changes.permissions !== undefined && !moves && !this.#authority.canReshare(record)) {
+                const { permissions: _inert, ...rest } = changes;
+                authorized = rest;
+            }
+        }
+        // A patch for another version is refused by `Stack`, which owes the
+        // tombstone and `ifVersion` refusals first; the content gates would read
+        // a stored Type it was not written for. Pinned to this read, `Stack`
+        // cannot find a record the patch lands on.
+        const mismatched = storedVersionDiffers(record, opts, changes.contentPatch !== undefined);
+        if (changes.contentPatch && !mismatched) {
+            const patch = changes.contentPatch;
+            // Value-wise, not presence-wise: a client that reads a card, edits
+            // its `name` and sends the whole content object back is not setting
+            // the binding it round-trips, and `name` is writable by record-level
+            // permission. Same predicate restoreVersion() applies to a snapshot.
+            this.requireOwnerForAppIdentity(record.typeId, (field) => field in patch && patch[field] !== record.content[field]);
+            // Likewise value-wise: re-sending the DID a card already holds
+            // claims nothing, and immutability refuses changing it regardless.
+            if ('did' in patch && patch.did !== record.content.did) {
+                this.requireOwnerForOwnerDid(record.typeId, patch.did);
+            }
+            await this.requireFileRefAccess(record.typeId, patch);
+        }
+        // Every association the change set would add is a reference this
+        // requester has to be allowed to create — asked against the stored
+        // set, so an association already on the record is not re-gated.
+        for (const assoc of changes.associations ?? []) {
+            if ((record.associations ?? []).some((a) => associationEqual(a, assoc)))
+                continue;
+            await this.requireAssociationAccess(record.typeId, assoc);
+        }
+        if (changes.parentId != null && !(await this.#authority.canReadReferent(changes.parentId))) {
+            throw new StackPermissionError(`Cannot reference record "${changes.parentId}" as parent: it does not exist or you cannot read it`);
+        }
+        const ifVersion = mismatched ? (opts.ifVersion ?? record.version) : opts.ifVersion;
+        return this.stack.mutate(id, authorized, { ...opts, ifVersion, ...this.actor });
+    }
+    async patchContent(id, patch, opts) {
+        return this.mutate(id, { contentPatch: patch }, opts);
+    }
+    /**
+     * The record, having established that this request may decide who else
+     * reaches it — the owner-or-creator rule, asked of both sides of a
+     * delegation, or a Group's admin rule for a `_group`. The gate the
+     * `permissions` and `unlisted` keys carry, which the write bit
+     * deliberately does not confer.
+     */
+    async requireReshareable(id, expect) {
+        const record = await this.stack.get(id, { includeDeleted: true });
+        if (!record)
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        checkFamily(record, expect);
+        await this.requireOwnerForGrantRecord(record);
+        await this.requireReshareOf(record);
+        return record;
+    }
+    /**
+     * Whether a change set's `permissions` key moves the ACL, read off the
+     * computed delta so a replacement that drops everything — naming nothing
+     * — still counts. See docs/spec/access-control.md § Record-level permissions.
+     */
+    permissionsMove(record, changes) {
+        if (changes.permissions === undefined)
+            return false;
+        return associationDelta(record.permissions ?? [], changes.permissions).length > 0;
+    }
+    /** The reshare decision alone, for a record already read and write-gated. */
+    async requireReshareOf(record) {
+        if (!this.#authority.canReshare(record)) {
+            throw await this.#authority.denialFor(record, `Cannot change permissions on "${record.id}": only its author or the stack owner can reshare it`);
+        }
+    }
+    /**
+     * An `_app` card's `did` and `appId` are the owner's alone to set, or
+     * record-level `write` would be a second way to name the software behind
+     * a key. `_entity` cards stay writable by grant, as a contacts app needs.
+     * See docs/spec/identity.md § DID bindings.
+     */
+    requireOwnerForAppIdentity(typeId, touches) {
+        if (baseIdOf(typeId) !== SYSTEM_TYPES.APP)
+            return;
+        if (!bindingFieldsOf(SYSTEM_TYPES.APP).some(touches))
+            return;
+        this.requireOwnerActingAlone('Only the stack owner may set an _app record’s did or appId');
+    }
+    /**
+     * A delegated write's `appId` must match the `_app` card the owner
+     * registered for the principal's DID, if there is one: a verified
+     * principal may not claim a name the owner gave other software.
+     * See docs/spec/identity.md § Attribution and what can be trusted.
+     */
+    async requireAppIdMatchesPrincipal(appId) {
+        const principal = this.#authority.principalId;
+        if (appId === undefined || !this.#authority.delegated || !principal)
+            return;
+        const card = await findAppCardByDid(this.stack, principal);
+        if (card && card.content.appId !== appId) {
+            throw new StackPermissionError(`appId "${appId}" is not the appId registered for this principal`);
+        }
+    }
+    /**
+     * The owner's own DID is the one `_entity` binding a grantee may not
+     * claim: `ownerProfile` adopts whichever card holds it.
+     * See docs/spec/identity.md § DID bindings.
+     */
+    requireOwnerForOwnerDid(typeId, did) {
+        if (baseIdOf(typeId) !== SYSTEM_TYPES.ENTITY)
+            return;
+        if (did !== this.stack.ownerEntityId)
+            return;
+        this.requireOwnerActingAlone('Only the stack owner may claim the owner’s own did');
+    }
+    /**
+     * `_grant` and `_install` Records are authority, so only the owner acting
+     * alone may write one; reading them stays on the ordinary gate.
+     * See docs/spec/access-control.md § What a grant covers.
+     */
+    async requireOwnerForGrantRecord(record) {
+        const family = baseIdOf(record.typeId);
+        if (family !== SYSTEM_TYPES.GRANT && family !== SYSTEM_TYPES.INSTALL)
+            return;
+        if (this.#authority.ownerActingAlone)
+            return;
+        throw await this.#authority.denialFor(record, `Only the stack owner may write a ${family} record`);
+    }
+    /**
+     * Gated on the write bit alone, which is why the list is held to its
+     * rules first: authority reached through this verb would be exactly the
+     * escalation the partition exists to stop, decided before any record is
+     * read so it cannot depend on who is asking.
+     */
+    async associate(id, associations, opts = {}) {
+        assertAssociationList(associations, 'associate()', 'associations', 'data');
+        return this.amendAssociations(id, editsOf('add', associations), opts, 'associate()');
+    }
+    /** See associate() — the same write gate, the same kind refusal. */
+    async dissociate(id, associations, opts = {}) {
+        assertAssociationList(associations, 'dissociate()', 'associations', 'data');
+        return this.amendAssociations(id, editsOf('remove', associations), opts, 'dissociate()');
+    }
+    /**
+     * The write gate, plus the per-element reference gate on each add: what a
+     * remove names is already on the record, so it is gated by the write bit
+     * alone. See associate().
+     */
+    async amendAssociations(id, changes, opts = {}, surface = 'amendAssociations()') {
+        assertAssociationEdits(changes, surface, 'data');
+        const record = await this.requireUpdatable(id, { expect: opts });
+        for (const change of changes) {
+            if (change.op === 'add')
+                await this.requireAssociationAccess(record.typeId, change.association);
+        }
+        return this.stack.amendAssociations(id, changes, { ...opts, ...this.actor }, surface);
+    }
+    /**
+     * Extend who reaches a record, on the reshare gate the `permissions` key
+     * carries. The write bit does not confer it, or a write-holder could
+     * decide who else reaches the record.
+     * See docs/spec/access-control.md § Record-level permissions.
+     */
+    async grantAccess(id, permissions, opts = {}) {
+        assertAssociationList(permissions, 'grantAccess()', 'permissions', 'authority');
+        return this.amendAccess(id, editsOf('add', permissions), opts, 'grantAccess()');
+    }
+    /** Withdraw elements of who reaches a record — see grantAccess(). */
+    async revokeAccess(id, permissions, opts = {}) {
+        assertAssociationList(permissions, 'revokeAccess()', 'permissions', 'authority');
+        return this.amendAccess(id, editsOf('remove', permissions), opts, 'revokeAccess()');
+    }
+    /** The reshare gate over an edit list — see grantAccess(). */
+    async amendAccess(id, changes, opts = {}, surface = 'amendAccess()') {
+        assertAssociationEdits(changes, surface, 'authority');
+        await this.requireReshareable(id, opts);
+        return this.stack.amendAccess(id, changes, { ...opts, ...this.actor }, surface);
+    }
+    /**
+     * Purge is owner-only: it is irreversible and destroys version
+     * history, so neither the write bit nor delete-own/delete-any grants
+     * reach it, and delegation doesn't carry it either. Everyone else is
+     * limited to soft delete.
+     */
+    async delete(id, opts = {}) {
+        const { referencedFileIds } = await this.deleteAndReturn(id, opts);
+        return { referencedFileIds };
+    }
+    /**
+     * delete(), plus the record it acted on. Gated identically — the
+     * existence/visibility check that produces a 404 ahead of the 403
+     * permission gate still runs via requireDeletable() before either kind
+     * of delete, so this changes what a successful call reports, not the
+     * disclosure ordering a refused one follows.
+     */
+    async deleteAndReturn(id, opts = {}) {
+        const record = await this.requireDeletable(id, opts);
+        if (opts.purge && !this.#authority.ownerActingAlone) {
+            throw new StackPermissionError('Purge is owner-only');
+        }
+        if (!opts[WRITE_EXPECTATION])
+            return this.stack.deleteAndReturn(id, { ...opts, ...this.actor });
+        // Checked against the read above, which the delete is pinned to.
+        // Forwarded, it would cost a purge the read `Stack` otherwise skips.
+        const { [WRITE_EXPECTATION]: _checked, ...rest } = opts;
+        return this.stack.deleteAndReturn(id, {
+            ...rest,
+            ifVersion: opts.ifVersion ?? record.version,
+            ...this.actor,
+        });
+    }
+    /**
+     * Reverse a soft delete. Gated the same as delete() — undelete is the
+     * inverse of soft delete, so granting one direction without the other
+     * would be backwards. Idempotent, per Stack.undelete().
+     */
+    async undelete(id, opts = {}) {
+        await this.requireDeletable(id, opts);
+        return this.stack.undelete(id, { ...opts, ...this.actor });
+    }
+    /**
+     * History is the mutation/recovery surface, not a read surface — gated
+     * like patchContent(). Reading it changes nothing, so it is the one path
+     * the `_grant` write fence leaves alone: seeing how a Record you can
+     * already read got that way is not the escalation that fence exists to
+     * stop. See docs/spec/versioning.md § History access.
+     */
+    async getVersions(id, query = {}) {
+        await this.requireUpdatable(id, { mutating: false });
+        return this.stack.getVersions(id, query);
+    }
+    /**
+     * See getVersions() — the same gate. A requester who may not reshare the
+     * record is served each `reshare` op without the elements beneath it.
+     * See docs/spec/journal.md § Reading it.
+     */
+    async getJournal(id, query = {}) {
+        const record = await this.requireUpdatable(id, { mutating: false });
+        const entries = await this.stack.getJournal(id, query);
+        return this.#authority.canReshare(record) ? entries : entries.map(withoutAuthorityChanges);
+    }
+    /** See getVersions() — the same mutate-surface gate. */
+    async getVersion(id, version) {
+        await this.requireUpdatable(id, { mutating: false });
+        return this.stack.getVersion(id, version);
+    }
+    /**
+     * Re-runs the reference-creation checks against the snapshot, so a
+     * restore can't re-convey access to a file the subject can no longer
+     * reach today. Only the owner acting alone is exempt: under delegation
+     * the checks resolve against the subject, which is whose reach the
+     * restore would widen. See docs/spec/versioning.md § Restore semantics.
+     */
+    async restoreVersion(id, version, opts = {}) {
+        const record = await this.requireUpdatable(id, { expect: opts });
+        if (!this.#authority.ownerActingAlone) {
+            const target = await this.stack.getVersion(id, version);
+            if (target) {
+                // A rollback that would move a card's binding is the same trust
+                // decision a content patch reserves to the owner, reached by another route.
+                this.requireOwnerForAppIdentity(record.typeId, (field) => target.content[field] !==
+                    record.content[field]);
+                await this.requireFileRefAccess(target.typeId, target.content);
+                // Content's file refs are the only reference a restore can put
+                // back: containment and associations are not on a snapshot at all,
+                // so a restore never introduces either — see
+                // docs/spec/versioning.md § Restore semantics.
+            }
+        }
+        return this.stack.restoreVersion(id, version, { ...opts, ...this.actor });
+    }
+    /**
+     * Commit a per-record migration: the owner acting alone, or an installed
+     * app within its own families (requireInstallMigration()). Ordinary write
+     * access is not consent to move a record between families.
+     * See docs/spec/access-control.md § What a grant covers.
+     */
+    async commitMigration(id, toTypeId, content, opts = {}) {
+        if (!this.#authority.ownerActingAlone)
+            await this.requireInstallMigration(id, toTypeId);
+        // The new content is a fresh set of file references, so an app is held
+        // to the gate create() applies; otherwise a migration could point one of
+        // its records at any attachment and read the bytes through it.
+        if (!this.#authority.ownerActingAlone)
+            await this.requireFileRefAccess(toTypeId, content);
+        return this.stack.commitMigration(id, toTypeId, content, { ...opts, ...this.actor });
+    }
+    /**
+     * Refuse a migration this request may not commit as an installed app —
+     * see ScopeAuthority.installMayMigrate(). The tombstone refusal comes
+     * only once authority is settled, as every mutating verb asks it: the
+     * owner may migrate a tombstone; an app sees it without content.
+     * See docs/spec/apps.md § Migrating an installed app's types.
+     */
+    async requireInstallMigration(id, toTypeId) {
+        const record = await this.stack.get(id, { includeDeleted: true });
+        if (!record || !(await this.#authority.installMayMigrate(record, toTypeId))) {
+            throw new StackPermissionError('Only the stack owner, or an installed app within the type families it defines, may commit a migration');
+        }
+        if (record.deletedAt) {
+            throw new StackConflictError(`Record "${id}" is soft-deleted; undelete it before migrating it.`);
+        }
+    }
+    /**
+     * Store bytes and create an _attachment@1 metadata record (create grant
+     * on `_attachment@1` required; anonymous denied), returning that record.
+     * Authorship and principal are stamped exactly as create() does.
+     */
+    async putAttachment(data, opts) {
+        const { appId } = opts;
+        // The one ScopedStack path that reaches the adapter without going
+        // through Stack first — without this, a closed stack would still write
+        // bytes before the delegated create() refused.
+        this.assertStackOpen();
+        const principal = this.#authority.principalId;
+        if (!principal) {
+            throw new StackPermissionError('Anonymous requesters cannot upload attachments');
+        }
+        await this.requireCreateGrant(`${SYSTEM_TYPES.ATTACHMENT}@1`);
+        await this.requireAppIdMatchesPrincipal(appId);
+        assertAttachmentSize(data.byteLength, this.capabilities.limits.attachmentBytes);
+        const fileId = await this.adapter.putBlob(data);
+        return this.stack.create(`${SYSTEM_TYPES.ATTACHMENT}@1`, uploadContent(fileId, data, opts), { createdBy: this.#authority.requester, appId });
+    }
+    /**
+     * Download attachment bytes. Accessible to the owner, a reader of any
+     * referencing record, or the uploader pre-association — the same
+     * predicate as the reference-creation gate (canAccessFile).
+     */
+    async getAttachment(fileId) {
+        if (!(await this.#authority.canAccessFile(fileId))) {
+            throw new StackPermissionError(`Cannot read file "${fileId}": it does not exist or you cannot read it`);
+        }
+        return this.stack.getAttachment(fileId);
+    }
+    /**
+     * Delete an attachment. Only the stack owner may delete attachments.
+     * Delegates to Stack.deleteAttachment(), which enforces the "not referenced" check.
+     */
+    async deleteAttachment(fileId) {
+        this.requireOwnerActingAlone('Only the stack owner can delete attachments');
+        return this.stack.deleteAttachment(fileId, this.actor);
+    }
+    /**
+     * Sweep for unreferenced attachment bytes and delete them. Only the stack
+     * owner may run this. Delegates to Stack.collectAttachmentGarbage().
+     */
+    async collectAttachmentGarbage(opts) {
+        this.requireOwnerActingAlone('Only the stack owner can collect attachment garbage');
+        return this.stack.collectAttachmentGarbage({ ...opts, ...this.actor });
+    }
+    /**
+     * Observe the changes this request may read, decided per event by the
+     * same canRead() that get() and query() use. An unreadable record yields
+     * no event at all, since a change's existence is itself a disclosure.
+     * See docs/spec/events.md § Permission scoping.
+     */
+    async subscribe(handler, opts = {}) {
+        this.assertStackOpen();
+        if (this.relaysChanges) {
+            throw new RelayScopeError('This stack relays changes from elsewhere, and a scoped view cannot narrow that feed: ' +
+                'a relayed frame was already scoped by the session that opened it, and a purge leaves ' +
+                'no record to re-check. Subscribe with a session-scoped stack instead.');
+        }
+        // A relaying stack was already refused above, so relaysChanges is
+        // always false here — `since` never has a cursor to mean anything by.
+        assertSinceUsable(opts.since, false);
+        assertValidBaseIdFilter(opts.filter);
+        if (opts.includeUnlisted && !this.#authority.ownerActingAlone) {
+            throw new StackPermissionError('includeUnlisted is owner-only');
+        }
+        return this.changes.add(new ScopedSubscription((record, cache) => this.canReadCached(record, cache), handler, opts));
+    }
+    /**
+     * canRead for one event, through the subscription's own cache. Grants
+     * are prefetched once and refilled after an invalidation rather than
+     * re-queried per event, which would be a `_grant` scan for every change
+     * the stack makes.
+     */
+    async canReadCached(record, cache) {
+        const grants = this.#authority.identified
+            ? await cache.grants(() => this.#authority.loadGrants())
+            : undefined;
+        return this.#authority.canRead(record, grants, cache.roles);
+    }
+}
+//# sourceMappingURL=scoped-stack.js.map