@haverstack/core 0.34.0 → 0.36.0

package/dist/scoped-stack.js

@@ -23,13 +23,13 @@ import { checkAccess, groupRoleFromAssociations, isOwnerActingAlone } from './ac
 import { ChangeEmitter, Subscription, matchesFilter, passesUnlistedBoundary, assertSinceUsable, } from './changes.js';
 import { SYSTEM_TYPES } from './types.js';
 import { StackConflictError, StackError, StackNotFoundError, StackPermissionError, StackRelayScopeError, StackValidationError, } from './errors.js';
-import { assertSortCapability, assertValidRelatedTo, assertValidSort, filtersContent, } from './query-validation.js';
-import { grantConveys, grantCoversGrantee, loadGrantRecords, UNGRANTABLE_SYSTEM_TYPES, } from './grants.js';
+import { assertAuthorityAssociations, assertDataAssociations, assertSortCapability, assertValidRelatedTo, assertValidSort, filtersContent, } from './query-validation.js';
+import { grantConveys, grantCoversGrantee, grantReach, loadGrantRecords, UNGRANTABLE_SYSTEM_TYPES, } from './grants.js';
 import { bindingFieldsOf } from './identity-bindings.js';
 import { assertAttachmentSize } from './limits.js';
 import { validateIdTimestampSkew, validateRecordId } from './record-id.js';
 import { DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, findFirstMatch, lookupEntityByDid, queryAllPages, } from './stack-reads.js';
-import { associationEqual, isGroupRecord, presentDeleted, stripVersionPermissions, assertNonEmptyChangeSet, } from './record-changes.js';
+import { associationDelta, associationEqual, isGroupRecord, presentDeleted, withoutAuthorityChanges, assertNonEmptyChangeSet, } from './record-changes.js';
 /**
  * The authority lookups canRead needs, held for the life of one
  * subscription. A subscription is long-lived where a query is not, so the
@@ -73,17 +73,11 @@ class FeedAuthorityCache {
  * lookups it needs cached for the life of the subscription and dropped the
  * moment anything that feeds them changes.
  *
- * Two properties do the work, and neither is optional:
- *
- * **Deliveries are serialized.** The permission decision is asynchronous,
- * so without a queue two changes to one record could resolve out of order
- * and be delivered newest-first — breaking the one ordering guarantee the
- * feed makes. Every emission is appended to a chain instead.
- *
- * **The filter fails closed.** A permission check that throws drops the
- * event and reports the error; it never delivers on the assumption that a
- * failed check would have passed.
- *
+ * Two properties do the work, and neither is optional. **Deliveries are
+ * serialized**, because the permission decision is asynchronous and two
+ * changes to one record could otherwise resolve out of order, breaking the
+ * feed's one ordering guarantee. And **the filter fails closed**: a check
+ * that throws drops the event and reports the error.
  * See docs/spec/events.md § Permission scoping.
  */
 class ScopedSubscription extends Subscription {
@@ -145,21 +139,16 @@ class ScopedSubscription extends Subscription {
  * cannot read answers exactly as a missing one does — null on reads,
  * StackNotFoundError on the verbs that name one — so only a requester who
  * could have read it is told a refusal was about access.
- * See docs/spec/access-control.md § Errors and information exposure.
+ * See docs/spec/disclosure.md § Which refusal a Record answers with.
  *
- * Two identities, one rule: **the principal governs authority, the subject
- * governs attribution.** Grant lookup and the privilege-bearing gates that
- * no grant reaches (resharing, group management, hard delete, widening
- * access at create time) key on `principalEntityId`; authorship, `-own`
- * matching, record-level permission resolution, and "files I uploaded"
- * lookups key on `subjectEntityId`.
- *
- * Unconditional owner access follows that same split rather than one
- * identity: it answers *what data is reachable* for the subject (an owner
- * subject resolves past every permission check) and *who may exercise a
- * privileged verb* for the principal (an owner app is not bounded by
- * grants). Under delegation both halves apply, and a mistake on the
- * authority side is an escalation rather than a preference.
+ * Which identity each gate keys on follows the module comment's rule.
+ * Grant lookup and the privilege-bearing gates no grant reaches
+ * (resharing, group management, hard delete, widening access at create
+ * time) key on `principalEntityId`; authorship, `-own` matching,
+ * record-level permission resolution and "files I uploaded" lookups key on
+ * `subjectEntityId`. Unconditional owner access splits the same way: an
+ * owner subject resolves past every permission check, an owner principal
+ * is not bounded by grants, and under delegation both halves apply.
  */
 export class ScopedStack {
     stack;
@@ -195,6 +184,16 @@ export class ScopedStack {
     get delegated() {
         return this.subjectEntityId !== this.principalEntityId;
     }
+    /**
+     * Whether any grant could name this request — the one question every
+     * prefetch asks before scanning the `_grant` family, since an anonymous
+     * requester is reached by none. Both identities are read: `asEntity()`
+     * refuses an anonymous principal acting for a subject, so they are null
+     * together, and saying so costs nothing.
+     */
+    get identified() {
+        return this.principalEntityId !== null || this.subjectEntityId !== null;
+    }
     /**
      * Who this request is, for stamping onto whatever it mutates. Attribution
      * follows record-level authorship: the subject is the actor, and the
@@ -221,11 +220,7 @@ export class ScopedStack {
     get ownerActingAlone() {
         return isOwnerActingAlone({ principalId: this.principalEntityId, subjectId: this.subjectEntityId }, this.stack.ownerEntityId);
     }
-    /**
-     * Refuse anything but the owner acting as itself. The verbs resting on
-     * this tier are irreversible or disclose the sharing graph, so delegation
-     * never carries one to a subject — see ownerActingAlone.
-     */
+    /** Refuse anything but the owner acting as itself — see ownerActingAlone. */
     requireOwnerActingAlone(message) {
         if (!this.ownerActingAlone)
             throw new StackPermissionError(message);
@@ -241,13 +236,12 @@ export class ScopedStack {
      * type's family (grants match by baseId, so a version bump never orphans
      * one). -own actions additionally require record.entityId === grantee,
      * unless `matchOwn` is false — on the principal side of a delegated
-     * request the suffix is read as the bare verb, since which records are
+     * request the suffix reads as the bare verb, since which records are
      * reachable is the subject's business. `allowDefault` decides whether a
-     * grant naming nobody counts. Anonymous grantees always return false.
+     * grant naming nobody counts.
      *
      * Reached only through subjectAllows()/principalAllows(), which fix those
-     * two flags per side of the intersection. Call one of those instead.
-     * See docs/spec/access-control.md § Type-level grants.
+     * two flags per side. Call one of those instead.
      */
     async hasGrant(typeId, actions, opts) {
         const { grantee, record, prefetchedGrants, matchOwn = true, allowDefault = true, allowGroup = true, } = opts;
@@ -276,7 +270,8 @@ export class ScopedStack {
         }
         for (const r of grantRecords) {
             const c = r.content;
-            if (baseIdOf(c.typeId) !== familyId)
+            const reach = grantReach(c);
+            if (!reach || reach.familyId !== familyId)
                 continue;
             const covers = await grantCoversGrantee(c, grantee, {
                 allowDefault,
@@ -287,7 +282,7 @@ export class ScopedStack {
             if (!covers)
                 continue;
             const matches = actions.some((action) => {
-                if (!grantConveys(c.actions, action))
+                if (!grantConveys(reach.actions, action))
                     return false;
                 if (matchOwn && action.endsWith('-own'))
                     return record?.entityId === grantee;
@@ -306,15 +301,11 @@ export class ScopedStack {
      * Vacuously true when there's no delegation, where the principal and
      * subject checks would be the same question asked twice.
      *
-     * Default grants don't count here. "Any authenticated entity" is about
-     * people who turn up, not software the owner installed — an app reaches
-     * only the types named to it, which is the whole of what containment
-     * promises.
-     *
-     * Group-targeted grants don't count here either, one step removed: a
-     * roster is editable by any of the group's admins, so authority reaching
-     * a principal through one would let someone other than the owner name an
-     * app to a type. See docs/spec/access-control.md § Type-level grants.
+     * Neither default nor group-targeted grants count here. "Any
+     * authenticated entity" is about people who turn up, not software the
+     * owner installed; and a roster is editable by any of the group's admins,
+     * so authority reaching a principal through one would let someone other
+     * than the owner name an app to a type.
      */
     principalAllows(typeId, actions, prefetchedGrants) {
         if (!this.delegated)
@@ -352,14 +343,14 @@ export class ScopedStack {
      * everyone else is told what a missing ID is told, so no one learns an ID
      * is live who could not have learned it by reading. `message` therefore
      * only ever reaches someone holding the record already.
-     * See docs/spec/access-control.md § Errors and information exposure.
+     * See docs/spec/disclosure.md § Which refusal a Record answers with.
      */
     async denialFor(record, message) {
         // Prefetched here rather than threaded down from the gate: a write
         // carried by a record-level permission settles without reading a grant
         // at all, and that path must not pay for this one. Both halves of
         // canRead share the one scan.
-        const grants = this.principalEntityId || this.subjectEntityId ? await this.loadGrants() : undefined;
+        const grants = this.identified ? await this.loadGrants() : undefined;
         if (await this.canRead(record, grants))
             return new StackPermissionError(message);
         return new StackNotFoundError(`Record not found: "${record.id}"`);
@@ -470,13 +461,10 @@ export class ScopedStack {
      * relationship target). Missing and unreadable both return false —
      * indistinguishable, so this can't probe for a record's existence.
      *
-     * The owner acting alone passes without the lookup, which costs nothing:
-     * there is no record in their own stack they may not read, so the gate
-     * could only ever refuse them for absence — and absence is `Stack`'s to
-     * answer, with the conflict that names the problem rather than a
-     * refusal standing in for it. The anti-oracle property is unchanged for
-     * every other requester.
-     * See docs/spec/access-control.md § Reference-creation gating.
+     * The owner acting alone passes without the lookup: there is no record in
+     * their own stack they may not read, so the gate could only refuse them
+     * for absence — which is `Stack`'s to answer, with a conflict that names
+     * the problem. See docs/spec/access-control.md § Reference-creation gating.
      */
     async canReadReferent(recordId) {
         if (this.ownerActingAlone)
@@ -489,18 +477,14 @@ export class ScopedStack {
     /**
      * Whether this request can read some record referencing `fileId` —
      * shared by canAccessFile() and the non-owner _attachment@1 create()
-     * carve-out, which deliberately excludes the uploader clause. Walks
-     * every referencing record, short-circuiting on the first readable one.
-     * `_attachment@1` records are excluded from matching outright: the
-     * carve-out must be satisfied by some *other* record referencing the
-     * file, never by the requester's own prior metadata record for it —
-     * allowing that would let one successful guess unlock unlimited further
-     * metadata records for the same fileId, reintroducing the circularity
-     * the carve-out's uploader-clause exclusion closes.
+     * carve-out, which deliberately excludes the uploader clause.
+     * `_attachment@1` records never match: the carve-out has to be satisfied
+     * by some *other* record referencing the file, or one successful guess
+     * would unlock unlimited further metadata records for the same fileId.
      * See docs/spec/attachments.md § Creating `_attachment@1` records directly.
      */
     async hasReadableReference(fileId) {
-        const prefetchedGrants = this.subjectEntityId ? await this.loadGrants() : undefined;
+        const prefetchedGrants = this.identified ? await this.loadGrants() : undefined;
         const groupRoles = new Map();
         const match = await findFirstMatch((q) => this.stack.query(q), 
         // Reach, not enumeration: a record readable by ID conveys the file it
@@ -533,17 +517,25 @@ export class ScopedStack {
         }
         if (this.subjectEntityId === this.stack.ownerEntityId)
             return true;
+        // `includeUnlisted`, as hasReadableReference() above: withholding a
+        // record from enumeration decides nothing about what it conveys, and
+        // the uploader clause does not lapse. See docs/spec/unlisted.md.
         return filtersContent(this.stack.features)
             ? (await this.stack.query({
                 filter: {
                     typeId: `${SYSTEM_TYPES.ATTACHMENT}@1`,
                     entityId: this.subjectEntityId,
                     content: { fileId },
+                    includeUnlisted: true,
                 },
                 limit: 1,
             })).records.length > 0
             : (await queryAllPages((q) => this.stack.query(q), {
-                filter: { typeId: `${SYSTEM_TYPES.ATTACHMENT}@1`, entityId: this.subjectEntityId },
+                filter: {
+                    typeId: `${SYSTEM_TYPES.ATTACHMENT}@1`,
+                    entityId: this.subjectEntityId,
+                    includeUnlisted: true,
+                },
             })).some((r) => r.content.fileId === fileId);
     }
     /** Names of the type's top-level file-ref fields — the content-reference half of attachmentFileId matching. */
@@ -607,26 +599,19 @@ export class ScopedStack {
      * creation refused save one carve-out. A scoped create always stamps
      * authorship — an absent entityId means an unscoped `Stack` wrote it.
      * `createdAt`/`updatedAt` are refused to everyone but the owner acting
-     * alone — see the guard below and docs/spec/data-model.md § Record IDs.
-     * See also docs/spec/access-control.md and docs/spec/attachments.md.
+     * alone, rather than dropped, so an app never believes it published
+     * something it didn't. See docs/spec/access-control.md and
+     * docs/spec/data-model.md § Record IDs.
      */
     async create(typeId, content, opts = {}) {
         const principal = this.principalEntityId;
         if (!principal)
             throw new StackPermissionError('Anonymous requesters cannot create records');
-        // createdAt/updatedAt let a caller backdate a record's clock fields —
-        // and, without `id` also supplied, its sort position too. Refused to
-        // everyone but the owner acting alone (undelegated, authenticated as
-        // themselves): a grantee is exactly the untrusted actor the `id`
-        // skew check below already 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 mayGrantAccess() below.
-        // Refused rather than silently dropped, so an app never believes it
-        // published something it didn't — asked value-wise, since an
+        // 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 mayGrantAccess() below. Asked value-wise, since an
         // `undefined` carries no date and Stack.create() reads it as absent.
-        // This is also the enforcement a server built on ScopedStack inherits
-        // for `POST /records`: an owner-authenticated request may carry both
-        // fields, anyone else's has them ignored.
         if ((opts.createdAt !== undefined || opts.updatedAt !== undefined) && !this.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.');
         }
@@ -705,7 +690,7 @@ export class ScopedStack {
      * 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/access-control.md § Errors and information exposure.
+     * See docs/spec/disclosure.md § Which refusal a Record answers with.
      */
     async get(id, opts = {}) {
         const record = await this.stack.get(id, opts);
@@ -744,7 +729,7 @@ export class ScopedStack {
         const records = [];
         const maxFetched = limit * 10;
         let totalFetched = 0;
-        const prefetchedGrants = this.principalEntityId ? await this.loadGrants() : undefined;
+        const prefetchedGrants = this.identified ? await this.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.
@@ -784,17 +769,48 @@ export class ScopedStack {
             if (patchErrors.length > 0)
                 throw new StackValidationError(patchErrors);
         }
-        const reshares = changes.permissions !== undefined || changes.unlisted !== undefined;
+        // 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 the key's presence alone: it is a boolean, so
+        // naming it is the whole of what it can say. `permissions` is a set,
+        // and a set restated is not a reshare — see permissionsMove() below,
+        // which refines the escalation on this branch alone. A change set
+        // naming no writable key is gated before any record is in hand to
+        // compute a delta from, so there it reshares on presence, like the
+        // boolean. 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) : await this.requireReshareable(id);
-        if (writes && reshares)
-            await this.requireReshareOf(record);
+        // Narrowed to what the gate below actually authorized. A key the gate
+        // read as inert is dropped rather than forwarded: `Stack` recomputes
+        // the delta against its own read of the record, so a key left standing
+        // on the strength of one read would write the ACL on the strength of
+        // another — and the set that reaches it is the one this requester saw,
+        // which is by then stale. 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.canReshare(record)) {
+                const { permissions: _inert, ...rest } = changes;
+                authorized = rest;
+            }
+        }
         if (changes.contentPatch) {
             const patch = changes.contentPatch;
             // Value-wise, not presence-wise: a client that reads a card, edits
@@ -820,7 +836,7 @@ export class ScopedStack {
         if (changes.parentId != null && !(await this.canReadReferent(changes.parentId))) {
             throw new StackPermissionError();
         }
-        return this.stack.mutate(id, changes, { ...opts, ...this.actor });
+        return this.stack.mutate(id, authorized, { ...opts, ...this.actor });
     }
     async patchContent(id, patch, opts = {}) {
         return this.mutate(id, { contentPatch: patch }, opts);
@@ -843,46 +859,54 @@ export class ScopedStack {
         // decision above, for the reason refuseIfDeleted() gives.
         return this.refuseIfDeleted(record, true);
     }
+    /**
+     * Whether a change set's `permissions` key actually moves the ACL. Read
+     * off the computed delta rather than the elements the caller supplied:
+     * a gate that inspected only what was named would miss the wholesale
+     * replacement that drops everything, which names nothing at all. Any
+     * add, remove or repoint in either direction is a reshare.
+     * 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 (baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP) {
-            // Group management, not authorship: a creator later demoted from the
-            // admin roster shouldn't retain a side door to reassign who can read
-            // or write the group record.
-            if (!this.isGroupManager(record))
-                throw await this.denialFor(record);
-            return;
-        }
-        // Intersected like every other authority here: the principal must hold
-        // the verb, and the subject must be able to reach this record —
-        // without which an owner principal would carry its subject to records
-        // the subject cannot touch. create() withholds the same reach via
-        // mayGrantAccess().
-        if (!this.mayReshare(this.principalEntityId, record))
+        if (!this.canReshare(record))
             throw await this.denialFor(record);
-        if (this.delegated && !this.mayReshare(this.subjectEntityId, record)) {
-            throw await this.denialFor(record);
-        }
+    }
+    /**
+     * Whether this request may decide who else reaches `record` — the
+     * decision requireReshareOf() refuses on, without the refusal, for the
+     * read paths that project on it rather than throw.
+     *
+     * A `_group` asks management, not authorship: a creator later demoted
+     * from the admin roster shouldn't retain a side door to reassign who can
+     * read or write the group record. Everything else is intersected like
+     * every other authority here, or an owner principal would carry its
+     * subject to records the subject cannot touch.
+     */
+    canReshare(record) {
+        if (baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP)
+            return this.isGroupManager(record);
+        if (!this.mayReshare(this.principalEntityId, record))
+            return false;
+        return !this.delegated || this.mayReshare(this.subjectEntityId, record);
     }
     /**
      * Naming the software behind a key is the trust decision the `_app`
      * registry exists to record, so both halves of that binding — `did` and
-     * `appId` — belong to the owner alone. Same reasoning that makes `_app`
-     * ungrantable, applied to the fields a lookup reads. Registering a card
-     * is already owner-only; without this, record-level `write` shared on a
-     * card would be a second way in: a card carrying no DID yet could be
-     * pointed at a write-holder's own key while keeping the name the owner
-     * gave it, or relabelled to claim another app's `appId`. `name` and
-     * `version` stay writable — they are display, not lookup.
-     *
-     * Owner *acting alone*, in both directions: a delegated app never holds
-     * it, and an owner principal doesn't lend it to a subject holding
-     * record-level `write` on a card — which would reopen the same route
-     * from the other side.
+     * `appId` — belong to the owner alone. Without this, record-level `write`
+     * on a card would be a second way in: one carrying no DID yet could be
+     * pointed at a write-holder's own key, or relabelled to claim another
+     * app's `appId`. `name` and `version` stay writable — display, not lookup.
      *
-     * `_entity` deliberately does not get this rule: naming people is what a
-     * contacts app does, so its cards stay writable by grant. Uniqueness and
-     * immutability still bind them. See docs/spec/identity.md § DID bindings.
+     * Owner *acting alone*, in both directions, or the same route reopens
+     * from the subject's side. `_entity` deliberately does not get this rule:
+     * naming people is what a contacts app does, so its cards stay writable
+     * by grant. See docs/spec/identity.md § DID bindings.
      */
     requireOwnerForAppIdentity(typeId, touches) {
         if (baseIdOf(typeId) !== SYSTEM_TYPES.APP)
@@ -893,13 +917,11 @@ export class ScopedStack {
     }
     /**
      * A self-reported `appId` must agree with the `_app` card naming the
-     * principal's DID, where the owner registered one. `principalId` is
+     * principal's DID, where the owner registered one: `principalId` is
      * verified, so letting the pair disagree would leave a verified principal
-     * claiming a name the owner gave different software — the cross-check the
-     * registry exists for, refused at the write instead of left to each reader.
-     * A principal with no card keeps `appId` as the bare self-report it is for
-     * every undelegated writer.
-     * See docs/spec/identity.md § Attribution and what can be trusted.
+     * claiming a name the owner gave different software. A principal with no
+     * card keeps `appId` as the bare self-report it is for every undelegated
+     * writer. See docs/spec/identity.md § Attribution and what can be trusted.
      */
     async requireAppIdMatchesPrincipal(appId) {
         if (appId === undefined || !this.delegated)
@@ -948,15 +970,43 @@ export class ScopedStack {
             return;
         throw await this.denialFor(record, 'Only the stack owner may write a _grant record');
     }
+    /**
+     * Gated on the write bit alone, which is why the kind refusal comes
+     * 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, association) {
+        assertDataAssociations([association], 'associate()');
         const record = await this.requireUpdatable(id);
         await this.requireAssociationAccess(record.typeId, association);
         return this.stack.associate(id, association, this.actor);
     }
+    /** See associate() — the same write gate, the same kind refusal. */
     async dissociate(id, association) {
+        assertDataAssociations([association], 'dissociate()');
         await this.requireUpdatable(id);
         return this.stack.dissociate(id, association, this.actor);
     }
+    /**
+     * Extend who reaches a record — the reshare gate's own verb, on the
+     * owner-or-creator rule the `permissions` key carries. The write bit
+     * does not confer it: a write-holder who could grant would escalate to
+     * deciding who else reaches the record, which is the whole of what
+     * scoping access is for.
+     * See docs/spec/access-control.md § Record-level permissions.
+     */
+    async grantAccess(id, permission) {
+        assertAuthorityAssociations([permission], 'grantAccess()');
+        await this.requireReshareable(id);
+        return this.stack.grantAccess(id, permission, this.actor);
+    }
+    /** Withdraw one element of who reaches a record — see grantAccess(). */
+    async revokeAccess(id, permission) {
+        assertAuthorityAssociations([permission], 'revokeAccess()');
+        await this.requireReshareable(id);
+        return this.stack.revokeAccess(id, permission, this.actor);
+    }
     /**
      * Hard delete is owner-only: it is irreversible and destroys version
      * history, so neither the write bit nor delete-own/delete-any grants
@@ -981,46 +1031,40 @@ export class ScopedStack {
     }
     /**
      * History is the mutation/recovery surface, not a read surface — gated
-     * like patchContent(), with snapshot `permissions` stripped for everyone but
-     * the owner acting alone — a snapshot's permissions are the stack's
-     * sharing graph, which delegation is not a route to. Reading history
-     * 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, and losing it would leave a
-     * write-holder unable to audit the Record they hold.
-     * See docs/spec/versioning.md § History access.
+     * 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) {
         await this.requireUpdatable(id, { mutating: false });
-        const versions = await this.stack.getVersions(id);
-        return this.ownerActingAlone ? versions : versions.map(stripVersionPermissions);
+        return this.stack.getVersions(id);
     }
     /**
      * See getVersions() — the same mutate-surface gate, for the same reason.
-     * A journal entry carries no snapshot `permissions` to strip: it names
-     * that a permission set moved, never what it moved to.
-     * See docs/spec/journal.md § Reading it.
+     *
+     * The journal is where a Record's sharing history lives, and that half
+     * is the resharer's: a reader who could not have moved the ACL is served
+     * the `permissions` op without the elements beneath it, so the entry
+     * still names that it moved. Asked of both identities, so delegation is
+     * no route to it either. See docs/spec/journal.md § Reading it.
      */
     async getJournal(id, query = {}) {
-        await this.requireUpdatable(id, { mutating: false });
-        return this.stack.getJournal(id, query);
+        const record = await this.requireUpdatable(id, { mutating: false });
+        const entries = await this.stack.getJournal(id, query);
+        return this.canReshare(record) ? entries : entries.map(withoutAuthorityChanges);
     }
-    /** See getVersions() — same mutate-surface gate, same permissions stripping. */
+    /** See getVersions() — the same mutate-surface gate. */
     async getVersion(id, version) {
         await this.requireUpdatable(id, { mutating: false });
-        const target = await this.stack.getVersion(id, version);
-        if (!target)
-            return null;
-        return this.ownerActingAlone ? target : stripVersionPermissions(target);
+        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 or record the subject can no
-     * longer reach today — the snapshot's `parentId` among them, gated
-     * exactly as a change set's `parentId` gates a destination named directly. 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.
+     * 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);
@@ -1031,50 +1075,28 @@ export class ScopedStack {
                 // decision a content patch reserves to the owner, reached by another route.
                 this.requireOwnerForAppIdentity(record.typeId, (field) => target.content[field] !==
                     record.content[field]);
-                // Only a restore that moves the record *into* a container creates a
-                // reference. A snapshot at the root names nothing, and a parentId
-                // the restore would not change is not re-gated: the record is
-                // already there, so a content rollback is not refused over a move
-                // it isn't making.
-                if (target.parentId !== undefined &&
-                    target.parentId !== record.parentId &&
-                    !(await this.canReadReferent(target.parentId))) {
-                    throw new StackPermissionError();
-                }
                 await this.requireFileRefAccess(target.typeId, target.content);
-                // No association gate: a snapshot never carries `associations`, so
-                // a restore never introduces one — see docs/spec/versioning.md
-                // § Restore semantics.
+                // 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, only**.
-     *
-     * Migration is owner-driven by design: `migrateAll()`, the bulk path,
-     * lives on `Stack` and is deliberately absent from `StackClient`, the
-     * same way `grant()`/`revoke()` are. This is its per-record counterpart
-     * and carries the same restriction, rather than inventing a grant model
-     * that the bulk path deliberately doesn't have.
+     * Commit a per-record migration — **the owner acting alone, only**, the
+     * same restriction the bulk `migrateAll()` carries by living on `Stack`.
      *
-     * The restriction is what makes the verb safe to expose at all. Migrate
-     * replaces `content` and `typeId` wholesale, so a grant-based version
-     * would have to re-derive every gate `create()` applies at the
+     * Migrate replaces `content` and `typeId` wholesale, so a grant-based
+     * version would have to re-derive every gate `create()` applies at the
      * destination *and* every gate `mutate()` applies over the existing
-     * content, and would reopen each one it missed. The sharpest is the
-     * non-owner `_attachment@1` refusal create() carries: without it, a
-     * requester holding a create grant on `_attachment@1` and write access
-     * to any record they authored could migrate that record into the family
-     * naming any `fileId`, then read the bytes through canAccessFile()'s
-     * uploader clause — the exact escalation that carve-out exists to refuse
-     * (see docs/spec/attachments.md § Creating `_attachment@1` records
-     * directly). Ordinary write access to a record is not consent to move it
-     * between families.
-     *
-     * A server implementing `POST /records/:id/migrate` therefore serves it
-     * to the stack owner and answers 403 otherwise. See
-     * docs/spec/data-model.md § Type migrations.
+     * content, reopening each one it missed. The sharpest is create()'s
+     * non-owner `_attachment@1` refusal: without it, a requester could
+     * migrate a record they authored into the family naming any `fileId` and
+     * read the bytes through canAccessFile()'s uploader clause. Ordinary
+     * write access to a record is not consent to move it between families.
+     * See docs/spec/data-model.md § Type migrations.
      */
     async commitMigration(id, toTypeId, content, opts = {}) {
         this.requireOwnerActingAlone('Only the stack owner may commit a migration');
@@ -1169,7 +1191,7 @@ export class ScopedStack {
      * the stack makes.
      */
     async canReadCached(record, cache) {
-        const grants = this.principalEntityId ? await cache.grants(() => this.loadGrants()) : undefined;
+        const grants = this.identified ? await cache.grants(() => this.loadGrants()) : undefined;
         return this.canRead(record, grants, cache.roles);
     }
 }