@haverstack/core 0.29.0 → 0.30.0

package/dist/record-id.js

@@ -0,0 +1,127 @@
+/**
+ * Record ID and clock-field validation
+ * -------------------------------------------------------
+ * The rules a caller-supplied `id`, `parentId`, `createdAt` or `updatedAt`
+ * is held to before any of them reaches storage. A client may mint its own
+ * id and backdate a record's clock, so both are untrusted input here even
+ * when the types say otherwise.
+ *
+ * See docs/spec/data-model.md § Record IDs.
+ */
+import { isValidIdFormat, idTimestamp, MAX_ID_TIMESTAMP } from './id.js';
+import { StackQueryError, StackValidationError } from './errors.js';
+// -------------------------------------------------------
+// Record ID validation
+// -------------------------------------------------------
+const RESERVED_ID_PREFIX = '_';
+export const DEFAULT_ID_TIMESTAMP_SKEW_MS = 24 * 60 * 60 * 1000;
+/**
+ * The same format rule applied to a `parentId` a caller names. Separate
+ * from validateRecordId() only for its message: the id under discussion is
+ * the destination, not the record being written, and a shared message would
+ * report the wrong one. See docs/spec/data-model.md § Reparenting.
+ */
+export function validateParentId(parentId) {
+    if (parentId.startsWith(RESERVED_ID_PREFIX)) {
+        throw new StackQueryError(`Invalid parentId "${parentId}": uses the reserved "${RESERVED_ID_PREFIX}" prefix.`);
+    }
+    if (!isValidIdFormat(parentId)) {
+        throw new StackQueryError(`Invalid parentId "${parentId}": expected 12 lowercase Crockford base-32 characters.`);
+    }
+}
+/**
+ * Format and reserved-prefix checks — full-trust context (Stack.create()).
+ * Checked before the format check: the Crockford charset already excludes
+ * "_", so a reserved-looking id (e.g. "_config") would otherwise just fail
+ * as a generic format error instead of a specific, actionable one.
+ *
+ * Throws StackQueryError, not StackValidationError: a malformed id is
+ * structurally bad input the request never gets past — it doesn't reach
+ * type-schema validation — the same reasoning that makes an undecodable
+ * pagination cursor a StackQueryError rather than a content-validation
+ * failure. See StackQueryError's doc comment.
+ */
+export function validateRecordId(id) {
+    if (id.startsWith(RESERVED_ID_PREFIX)) {
+        throw new StackQueryError(`ID "${id}" uses the reserved "${RESERVED_ID_PREFIX}" prefix.`);
+    }
+    if (!isValidIdFormat(id)) {
+        throw new StackQueryError(`Invalid ID "${id}": expected 12 lowercase Crockford base-32 characters.`);
+    }
+}
+/**
+ * Validity and range check for the backdating options on unscoped
+ * Stack.create(). A Date is only as good as what the caller parsed it
+ * from, and the two failure modes both need catching here rather than
+ * downstream:
+ *
+ * - **Invalid Date** (`new Date('13/45/2020')` off a malformed import row)
+ *   has a NaN getTime(), and every comparison against NaN is false — so an
+ *   unchecked Invalid Date passes the updatedAt/createdAt ordering check
+ *   and the id/createdAt skew check by turning them off, mints the
+ *   epoch-zero ID `000000000xxx`, and persists a record whose
+ *   `createdAt.toISOString()` throws RangeError in serializeRecord() —
+ *   making that record, and any wire response containing it,
+ *   permanently unreadable.
+ * - **Out of encodable range** — before 1970 crockford32Encode() throws a
+ *   bare RangeError from deep inside the ID encoder, and past
+ *   MAX_ID_TIMESTAMP the derived ID silently grows to 13 characters and
+ *   fails isValidIdFormat().
+ *
+ * Checked at the door for both, as a StackValidationError naming the
+ * field. Applies whether or not an `id` is supplied: a clock field outside
+ * this range is unrepresentable regardless of where the ID came from.
+ */
+export function validateClockField(value, path) {
+    if (value === undefined)
+        return [];
+    // Type-checked callers always pass a Date, but this option is now
+    // reachable from the wire: JSON has no Date, so a server that forwards a
+    // parsed `POST /records` body hands us the ISO *string* it deserialized.
+    // Without this the very next line is `"2020-…".getTime()` — an unhandled
+    // TypeError, a 500 where the caller should have got a 400 naming the
+    // field.
+    if (!(value instanceof Date)) {
+        return [{ path, message: `${path} must be a Date.` }];
+    }
+    const ms = value.getTime();
+    if (Number.isNaN(ms)) {
+        return [{ path, message: `${path} is not a valid Date.` }];
+    }
+    if (ms < 0 || ms > MAX_ID_TIMESTAMP) {
+        return [
+            {
+                path,
+                message: `${path} is outside the representable range ` +
+                    `(1970-01-01T00:00:00.000Z…${new Date(MAX_ID_TIMESTAMP).toISOString()}).`,
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Timestamp-prefix plausibility check, shared by callers that compare an
+ * ID's embedded millisecond against a different reference each:
+ * ScopedStack.create() against the current time for any non-backdated
+ * create (a grantee is untrusted and could otherwise mint an ID that
+ * forges its sort position, and this is the one check standing between a
+ * delegated or grantee caller and doing so), and Stack.create() — reached
+ * directly when unscoped, or via ScopedStack.create() when the requester
+ * is the owner acting alone with an explicit `createdAt` — against that
+ * `createdAt` instead (the two must agree, not silently diverge — see
+ * docs/spec/data-model.md § Record IDs). Pass null to disable.
+ */
+export function validateIdTimestampSkew(id, toleranceMs, referenceMs, referenceLabel) {
+    if (toleranceMs === null)
+        return;
+    const skew = Math.abs(referenceMs - idTimestamp(id));
+    if (skew > toleranceMs) {
+        throw new StackValidationError([
+            {
+                path: 'id',
+                message: `ID "${id}" timestamp disagrees with ${referenceLabel} by more than the allowed clock-skew tolerance (${toleranceMs}ms).`,
+            },
+        ]);
+    }
+}
+//# sourceMappingURL=record-id.js.map

package/dist/record-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-id.js","sourceRoot":"","sources":["../src/record-id.ts"],"names":[],"mappings":"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"}

package/dist/scoped-stack.d.ts

@@ -0,0 +1,460 @@
+/**
+ * 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.
+ *
+ * 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 { ChangeEmitter } from './changes.js';
+import type { AppId, Association, AttachmentContent, EntityId, QueryResult, RecordChange, RecordVersion, StackAdapter, StackFeatures, StackQuery, StackRecord, SubscribeOptions, TypeId, Unsubscribe, RecordChanges } from './types.js';
+import type { Stack, BackdatableCreateRecordOptions, CollectAttachmentGarbageOptions, CollectAttachmentGarbageResult, DeleteRecordOptions, GetRecordOptions, IfVersionOptions, StackClient } from './stack.js';
+/**
+ * A permission-enforcing view of a Stack for a single (principal, subject)
+ * pair, obtained via `stack.asEntity(entityId)`. A record the request
+ * 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.
+ *
+ * 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.
+ */
+export declare class ScopedStack implements StackClient {
+    private readonly stack;
+    private readonly principalEntityId;
+    private readonly subjectEntityId;
+    private readonly idTimestampSkewMs;
+    private readonly adapter;
+    private readonly changes;
+    constructor(stack: Stack, principalEntityId: EntityId | null, subjectEntityId: EntityId | null, idTimestampSkewMs: number | null, adapter: StackAdapter, changes: ChangeEmitter);
+    get features(): StackFeatures;
+    private resolveRecord;
+    /** Every `_grant` Record — see loadGrantRecords(). */
+    private loadGrants;
+    /** Whether a delegated app is acting for someone other than itself. */
+    private get delegated();
+    /**
+     * Who this request is, for stamping onto whatever it mutates. Attribution
+     * follows record-level authorship: the subject is the actor, and the
+     * principal is named beside it only when the two differ.
+     * See docs/spec/data-model.md § Authorship and attribution.
+     */
+    private get actor();
+    /**
+     * Whether unconditional owner authority applies — the owner acting as
+     * itself. The verbs that rest on it are irreversible or disclose the
+     * sharing graph, so delegation never carries one to a subject, whichever
+     * side the owner is on. Shared with the predicate a server applies to a
+     * session, which decides the same tier one step earlier. See
+     * docs/spec/access-control.md § Delegation: principal and subject.
+     */
+    private get ownerActingAlone();
+    /**
+     * 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.
+     */
+    private requireOwnerActingAlone;
+    private checkRead;
+    private checkWrite;
+    /**
+     * Whether `grantee` holds a _grant covering one of `actions` for the
+     * 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
+     * reachable is the subject's business. `allowDefault` decides whether a
+     * grant naming nobody counts. Anonymous grantees always return false.
+     *
+     * 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.
+     */
+    private hasGrant;
+    /**
+     * The principal half of a delegated request's authority: does the app
+     * hold any grant permitting these verbs on this type at all. Bounds what
+     * the subject's own authority can reach through it, so a powerful app
+     * can never lend its reach to a weaker subject — nor the reverse.
+     * 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.
+     */
+    private principalAllows;
+    /**
+     * The subject half: which records are reachable, answered with `-own`
+     * matching and default grants both in force — the ordinary reading of a
+     * grant, since the subject is the entity a grant is written about.
+     *
+     * Paired with principalAllows() so that the two halves of the
+     * intersection are the only callers of hasGrant(): its flags differ per
+     * side and mean nothing on their own, so no call site sets them by hand.
+     */
+    private subjectAllows;
+    /**
+     * How to refuse a record this request addressed by ID. A requester who
+     * can read the record is told it exists and the verb was refused;
+     * 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.
+     */
+    private denialFor;
+    private canRead;
+    private checkCreateGrant;
+    /**
+     * `_group` records are managed, not merely written: only the owner or an
+     * `admin` roster holder may mutate them — ordinary write permissions and
+     * grants don't apply. Asked of both identities under delegation, like
+     * a reshare. See docs/spec/identity.md § Group.
+     */
+    private isGroupManager;
+    /** Whether one identity, on its own, manages `record` — see isGroupManager(). */
+    private managesGroup;
+    /**
+     * 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.
+     */
+    private requireUpdatable;
+    /**
+     * 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.
+     */
+    private requireVerb;
+    /**
+     * Refuse a mutation aimed at a soft-deleted Record. Asked only of a
+     * mutating caller, so the history readers borrowing this gate still work,
+     * and only after the authority decision, so "exists but deleted" is never
+     * a probe a stranger can run. See docs/spec/versioning.md § Mutations are
+     * refused, not applied to a tombstone.
+     */
+    private refuseIfDeleted;
+    /**
+     * Fetch a record the subject can reach and the principal holds `delete` on
+     * (via permissions or a delete grant), or throw.
+     */
+    private requireDeletable;
+    /**
+     * Whether this request may reference `recordId` (as a parentId or
+     * relationship target). Missing and unreadable both return false —
+     * indistinguishable, so this can't probe for a record's existence.
+     */
+    private canReadReferent;
+    /**
+     * 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.
+     * See docs/spec/attachments.md § Creating `_attachment@1` records directly.
+     */
+    private hasReadableReference;
+    /**
+     * Whether this request may reference or download `fileId` — the dual of
+     * getAttachment()'s access rule. Nonexistent and inaccessible are
+     * indistinguishable (both false), so no confirmation oracle for guessed
+     * hashes. See docs/spec/access-control.md § Reference-creation gating.
+     */
+    private canAccessFile;
+    /** Names of the type's top-level file-ref fields — the content-reference half of attachmentFileId matching. */
+    private fileRefFieldNames;
+    /**
+     * 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).
+     */
+    private requireFileRefAccess;
+    /**
+     * Reference-creation gate for one association: `attachment` requires
+     * file access, and a `relationship` naming a record in this stack
+     * requires read access to it. `tag` is unchecked, and `_group` roster
+     * associations are gated by the stricter isGroupManager() instead.
+     *
+     * The other target arms are ungated because the gate's purpose —
+     * refusing a reference that would convey access to, or confirm the
+     * existence of, an unreadable record — has nothing to bite on: core
+     * never resolves them, so no access flows through one.
+     * See docs/spec/access-control.md § Reference-creation gating.
+     */
+    private requireAssociationAccess;
+    /**
+     * Create a record on behalf of the subject: create grant required,
+     * anonymous denied, entityId set to the subject, client IDs skew-checked,
+     * reference-creating options gated, and non-owner `_attachment@1`
+     * 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.
+     */
+    create<T extends Record<string, unknown> = Record<string, unknown>>(typeId: TypeId, content: T, opts?: BackdatableCreateRecordOptions): Promise<StackRecord & {
+        content: T;
+    }>;
+    /**
+     * Whether this request may decide who else reaches a record — the rule
+     * a reshare enforces, asked at create time too so the reach it
+     * withholds can't be taken one step earlier while authoring. A delegated
+     * app is denied it: widening access is the one thing containment most
+     * needs to hold. Refused rather than silently ignored, so an app never
+     * believes it published something it didn't. Not `ownerActingAlone`:
+     * the record is the subject's own, so an owner principal grants it no
+     * reach the subject lacks.
+     * See docs/spec/access-control.md § Delegation: principal and subject.
+     */
+    private mayGrantAccess;
+    /**
+     * Whether one identity, on its own, may decide who else reaches `record`
+     * — the owner-or-creator rule a reshare enforces, asked of one
+     * side at a time. See
+     * docs/spec/access-control.md § Delegation: principal and subject.
+     */
+    private mayReshare;
+    /**
+     * 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.
+     */
+    get(id: string, opts?: GetRecordOptions): Promise<StackRecord | null>;
+    /**
+     * 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.
+     */
+    getEntityByDid(did: EntityId): Promise<StackRecord | null>;
+    getOwnerEntity(): Promise<StackRecord | null>;
+    /**
+     * 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.
+     */
+    query(query?: StackQuery): Promise<QueryResult>;
+    /**
+     * Apply a change set on behalf of the subject. Authority is resolved
+     * **per key** and every gate reads the record as it stands, never as the
+     * change set would leave it: a widened `permissions` never satisfies the
+     * read check on a `parentId` named in the same call, and a `_group`
+     * roster never satisfies the admin check that same call has to pass.
+     * One refused key refuses the whole call, so nothing is partially
+     * applied and no key is silently dropped.
+     * See docs/spec/access-control.md § Composing a change set.
+     */
+    mutate(id: string, changes: RecordChanges, opts?: IfVersionOptions): Promise<StackRecord>;
+    patchContent(id: string, patch: Record<string, unknown | null>, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * 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.
+     */
+    private requireReshareable;
+    /** The reshare decision alone, for a record already read and write-gated. */
+    private requireReshareOf;
+    /**
+     * 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.
+     *
+     * `_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.
+     */
+    private requireOwnerForAppIdentity;
+    /**
+     * A self-reported `appId` must agree with the `_app` card naming the
+     * 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.
+     */
+    private requireAppIdMatchesPrincipal;
+    /**
+     * The owner's own DID is the one `_entity` binding a grantee may not claim.
+     * `ownerProfile` adopts whichever card holds it, so a card minted by
+     * someone else becomes the stack's own profile, and uniqueness then makes
+     * that permanent. Every other DID stays open to a contacts app, which is
+     * the reach `_entity` is grantable for.
+     * See docs/spec/identity.md § DID bindings.
+     */
+    private requireOwnerForOwnerDid;
+    /**
+     * A `_grant` Record *is* authority, so rewriting one is the escalation
+     * UNGRANTABLE_SYSTEM_TYPES refuses at evaluation, reached by editing an
+     * existing grant rather than minting a fresh one. `grant()` and `revoke()`
+     * live on `Stack`, never `StackClient`, so no scoped write is lost. Writes
+     * only: reading a grant Record and its history stays on the ordinary gate.
+     * See docs/spec/access-control.md § Type-level grants.
+     */
+    private requireOwnerForGrantRecord;
+    associate(id: string, association: Association, opts?: IfVersionOptions): Promise<StackRecord>;
+    dissociate(id: string, association: Association, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * Hard delete 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.
+     */
+    delete(id: string, opts?: DeleteRecordOptions): Promise<void>;
+    /**
+     * 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().
+     */
+    undelete(id: string, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * 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.
+     */
+    getVersions(id: string): Promise<RecordVersion[]>;
+    /** See getVersions() — same mutate-surface gate, same permissions stripping. */
+    getVersion(id: string, version: number): Promise<RecordVersion | null>;
+    /**
+     * 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.
+     */
+    restoreVersion(id: string, version: number, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * 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.
+     *
+     * 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
+     * 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.
+     */
+    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * 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.
+     */
+    putAttachment(data: Uint8Array, mimeType: string, filename?: string, appId?: AppId): Promise<StackRecord & {
+        content: AttachmentContent;
+    }>;
+    /**
+     * 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).
+     */
+    getAttachment(fileId: string): Promise<Uint8Array>;
+    /**
+     * Delete an attachment. Only the stack owner may delete attachments.
+     * Delegates to Stack.deleteAttachment(), which enforces the "not referenced" check.
+     */
+    deleteAttachment(fileId: string): Promise<void>;
+    /**
+     * Sweep for unreferenced attachment bytes and delete them. Only the stack
+     * owner may run this. Delegates to Stack.collectAttachmentGarbage().
+     */
+    collectAttachmentGarbage(opts?: CollectAttachmentGarbageOptions): Promise<CollectAttachmentGarbageResult>;
+    /**
+     * Observe the changes this request may read. The predicate is canRead
+     * applied per event — the same one get() and query() answer with, so a
+     * feed can't disagree with them about what this session sees.
+     *
+     * A record the subscriber cannot read produces no event at all, rather
+     * than an empty or redacted one: the existence of a change is itself a
+     * disclosure, the same reasoning that keeps a count of the whole match
+     * off a query result. See docs/spec/events.md § Permission scoping.
+     */
+    subscribe(handler: (change: RecordChange) => void, opts?: SubscribeOptions): Promise<Unsubscribe>;
+    /**
+     * 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.
+     */
+    private canReadCached;
+}
+//# sourceMappingURL=scoped-stack.d.ts.map

package/dist/scoped-stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-stack.d.ts","sourceRoot":"","sources":["../src/scoped-stack.ts"],"names":[],"mappings":"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"}