@haverstack/core 0.13.1 → 0.15.0

package/dist/stack.js

@@ -19,7 +19,7 @@ import { validateContent, validateReservedKeys } from './validate.js';
 import { applyMergePatch } from './merge.js';
 import { checkAccess, groupRoleFromAssociations, validatePermissions } from './access.js';
 import { firstRecordedAttachment } from './attachment-download.js';
-import { ChangeEmitter, RelayDelivery, Subscription, buildEmission, matchesFilter, } from './changes.js';
+import { ChangeEmitter, RelayDelivery, Subscription, buildEmission, matchesFilter, passesUnlistedBoundary, } from './changes.js';
 import { SYSTEM_TYPES, GRANT_ACTIONS } from './types.js';
 // -------------------------------------------------------
 // Supporting types
@@ -324,6 +324,78 @@ export function assertValidSort(sort) {
         throw new StackQueryError(`Invalid sort direction "${sort.direction}": expected "asc" or "desc".`);
     }
 }
+/** The identifier spaces a relationship target may name. */
+const TARGET_SCOPES = new Set(['record', 'entity', 'external']);
+/**
+ * Collect what makes a relationship target malformed. Absence is
+ * meaningful on `stackUrl` and an external `id` — this stack, and the
+ * whole namespace — so every part that names something must be non-empty:
+ * an empty string stores and matches as though it were absent.
+ * See docs/spec/data-model.md § Relationship targets.
+ */
+function targetErrors(target, path, opts = {}) {
+    const fail = (message) => [{ path, message }];
+    if (!target || typeof target !== 'object')
+        return fail('A relationship target must be an object.');
+    if (!TARGET_SCOPES.has(target.scope)) {
+        return fail(`Unknown relationship target scope "${target.scope}": expected "record", "entity" or "external".`);
+    }
+    if (target.scope === 'record') {
+        if (!target.recordId)
+            return fail('A record target requires a non-empty recordId.');
+        if (target.stackUrl !== undefined && !target.stackUrl) {
+            return fail("A record target's stackUrl must be non-empty; omit it to name this stack.");
+        }
+        return [];
+    }
+    if (target.scope === 'entity') {
+        return target.entityId ? [] : fail('An entity target requires a non-empty entityId.');
+    }
+    if (!target.ns)
+        return fail('An external target requires a non-empty ns.');
+    if (target.id === undefined) {
+        return opts.externalIdOptional ? [] : fail('An external target requires an id.');
+    }
+    return target.id ? [] : fail("An external target's id must be non-empty when present.");
+}
+/**
+ * Reject a relationship target outside the closed set the types promise.
+ * A discriminated union is not a runtime guard — a server mapping a
+ * request body onto an association supplies raw JSON — and an
+ * unrecognized scope would otherwise be stored under the one arm that
+ * names a Record in this stack. See docs/spec/data-model.md
+ * § Relationship targets.
+ */
+function validateAssociation(association, path = 'association') {
+    if (association?.kind !== 'relationship')
+        return [];
+    return targetErrors(association.target, `${path}.target`);
+}
+/** validateAssociation() over a create's `associations` array. */
+function validateAssociations(associations, path = 'associations') {
+    return (associations ?? []).flatMap((a, i) => validateAssociation(a, `${path}[${i}]`));
+}
+/**
+ * Reject a relationship filter that names neither a label nor a target,
+ * or whose target is malformed. `RelatedToFilter` promises one half is
+ * always present; without the runtime check a filter decoded from a
+ * request could arrive empty and match every record carrying any
+ * relationship. See docs/spec/data-model.md § Filter.
+ */
+export function assertValidRelatedTo(relatedTo) {
+    if (!relatedTo)
+        return;
+    if (relatedTo.label === undefined && relatedTo.target === undefined) {
+        throw new StackQueryError('filter.relatedTo must name a label, a target, or both — "any relationship at all" is not a filter.');
+    }
+    if (relatedTo.target === undefined)
+        return;
+    const errors = targetErrors(relatedTo.target, 'filter.relatedTo.target', {
+        externalIdOptional: true,
+    });
+    if (errors.length > 0)
+        throw new StackQueryError(errors[0].message);
+}
 /**
  * Thrown when an attachment upload exceeds the adapter's declared
  * `maxAttachmentBytes` ceiling — checked client-side before any bytes are
@@ -617,7 +689,7 @@ export class Stack {
      */
     async ensureOwnerEntity(profile) {
         const entityTypeId = `${SYSTEM_TYPES.ENTITY}@1`;
-        const existing = await findFirstMatch((q) => this.query(q), { filter: { baseId: SYSTEM_TYPES.ENTITY, includeDeleted: true } }, (r) => r.content.did === this.ownerEntityId);
+        const existing = await findFirstMatch((q) => this.query(q), { filter: { baseId: SYSTEM_TYPES.ENTITY, includeDeleted: true, includeUnlisted: true } }, (r) => r.content.did === this.ownerEntityId);
         if (existing)
             return;
         await this.create(entityTypeId, {
@@ -826,7 +898,7 @@ export class Stack {
             let cursor;
             do {
                 const result = await this.adapter.queryRecords({
-                    filter: { typeId, includeDeleted: true },
+                    filter: { typeId, includeDeleted: true, includeUnlisted: true },
                     limit: 100,
                     cursor,
                 });
@@ -862,6 +934,7 @@ export class Stack {
             ...validateReservedKeys(content),
             ...validateContent(content, type.schema),
             ...validatePermissions(opts.permissions),
+            ...validateAssociations(opts.associations),
         ];
         if (errors.length > 0) {
             throw new StackValidationError(errors);
@@ -895,6 +968,7 @@ export class Stack {
             ...(opts.principalId && { updatedVia: opts.principalId }),
             ...(opts.permissions?.length && { permissions: opts.permissions }),
             ...(associations?.length && { associations }),
+            ...(opts.unlisted && { unlistedAt: now }),
         };
         const created = await this.adapter.createRecord(record);
         this.emitChange('create', created);
@@ -998,6 +1072,9 @@ export class Stack {
      */
     async associate(id, association, opts = {}) {
         this.assertOpen();
+        const errors = validateAssociation(association);
+        if (errors.length > 0)
+            throw new StackValidationError(errors);
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
@@ -1019,6 +1096,9 @@ export class Stack {
      */
     async dissociate(id, association, opts = {}) {
         this.assertOpen();
+        const errors = validateAssociation(association);
+        if (errors.length > 0)
+            throw new StackValidationError(errors);
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
@@ -1060,6 +1140,35 @@ export class Stack {
         });
         this.emitChange('permissions', updated);
     }
+    /**
+     * Withhold a record from enumeration, or restore it. Orthogonal to
+     * setPermissions(): it says nothing about who may read the record, only
+     * whether `query()` and the change feed enumerate it by default. No-op if
+     * already in the requested state. See docs/spec/access-control.md §
+     * Unlisted records.
+     *
+     * The op passed to emitChange() carries the transition direction —
+     * `unlist` (kind `deleted`, so subscribers already holding the record are
+     * told to drop it) or `list` (kind `changed`, an upsert like `undelete`,
+     * for the record's publish moment).
+     */
+    async setUnlisted(id, unlisted, opts = {}) {
+        this.assertOpen();
+        const existing = await this.adapter.getRecord(id);
+        if (!existing) {
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        }
+        this.checkIfVersion(existing, opts.ifVersion);
+        if (Boolean(existing.unlistedAt) === unlisted)
+            return;
+        const updated = await this.adapter.setUnlisted(id, unlisted, {
+            expectedVersion: opts.ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
+        });
+        this.emitChange(unlisted ? 'unlist' : 'list', updated);
+    }
     /**
      * Soft-delete a record (default) or hard-delete it permanently, removing
      * the record and its version history. Soft delete snapshots and bumps
@@ -1136,6 +1245,7 @@ export class Stack {
         const { presentAt, filter, limit: rawLimit, ...rest } = query;
         assertQueryCapabilities(filter, this.adapter.capabilities);
         assertValidSort(query.sort);
+        assertValidRelatedTo(filter?.relatedTo);
         const limit = rawLimit !== undefined ? Math.min(rawLimit, MAX_QUERY_LIMIT) : undefined;
         const resolvedFilter = await this.resolveBaseIdFilter(filter);
         if (resolvedFilter === EMPTY_FAMILY) {
@@ -1397,6 +1507,7 @@ export class Stack {
             filter: {
                 baseId: family,
                 includeDeleted: true,
+                includeUnlisted: true,
                 ...(this.features.contentFieldQuery && { content: { [field]: value } }),
             },
         }, (r) => r.id !== excludeId && r.content[field] === value);
@@ -1451,6 +1562,7 @@ export class Stack {
             filter: {
                 typeId: metadataTypeId,
                 includeDeleted: true,
+                includeUnlisted: true,
                 ...(this.features.contentFieldQuery && { content: { fileId } }),
             },
         });
@@ -1608,22 +1720,24 @@ export class Stack {
      * race between the reference check below and the deletes it guards.
      */
     async deleteUnreferencedAttachmentRecordsFallback(fileId, metadataTypeId, opts = {}) {
-        // A soft-deleted record still counts as a reference — it must find its
-        // attachments intact on undelete. See docs/spec/attachments.md
-        // § Deleting attachments.
+        // A soft-deleted or unlisted record still counts as a reference — it
+        // must find its attachments intact on undelete or relisting. See
+        // docs/spec/attachments.md § Deleting attachments.
         const refResult = await this.query({
-            filter: { attachmentFileId: fileId, includeDeleted: true },
+            filter: { attachmentFileId: fileId, includeDeleted: true, includeUnlisted: true },
             limit: 1,
         });
         if (refResult.records.length > 0) {
             throw new StackConflictError('Attachment is still referenced by one or more records');
         }
-        // Cursor-walk with includeDeleted: metadata past page one, or soft-
-        // deleted, must be cleaned up too — not left pointing at deleted bytes.
+        // Cursor-walk with includeDeleted/includeUnlisted: metadata past page
+        // one, soft-deleted, or unlisted must be cleaned up too — not left
+        // pointing at deleted bytes.
         const metaResults = await queryAllPages((q) => this.query(q), {
             filter: {
                 typeId: metadataTypeId,
                 includeDeleted: true,
+                includeUnlisted: true,
                 ...(this.features.contentFieldQuery && { content: { fileId } }),
             },
         });
@@ -1648,7 +1762,7 @@ export class Stack {
         const now = Date.now();
         const metadataTypeId = `${SYSTEM_TYPES.ATTACHMENT}@1`;
         const metaRecords = await queryAllPages((q) => this.query(q), {
-            filter: { typeId: metadataTypeId, includeDeleted: true },
+            filter: { typeId: metadataTypeId, includeDeleted: true, includeUnlisted: true },
         });
         // Newest metadata record's createdAt per fileId, and its size (constant
         // across records sharing a fileId, since content-addressing guarantees
@@ -1675,7 +1789,7 @@ export class Stack {
         let reclaimedBytes = 0;
         for (const fileId of candidateFileIds) {
             const refResult = await this.query({
-                filter: { attachmentFileId: fileId, includeDeleted: true },
+                filter: { attachmentFileId: fileId, includeDeleted: true, includeUnlisted: true },
                 limit: 1,
             });
             if (refResult.records.length > 0)
@@ -1761,6 +1875,7 @@ export class Stack {
         const stop = await this.adapter.subscribeChanges({
             ...(opts.filter !== undefined && { filter: opts.filter }),
             ...(opts.includeRecords !== undefined && { includeRecords: opts.includeRecords }),
+            ...(opts.includeUnlisted !== undefined && { includeUnlisted: opts.includeUnlisted }),
             ...(opts.onError !== undefined && { onError: opts.onError }),
             ...(opts.onReset !== undefined && { onReset: opts.onReset }),
         }, (change) => delivery.deliver(change));
@@ -2033,17 +2148,31 @@ export class Stack {
 // -------------------------------------------------------
 /**
  * Matches the SQLite adapter's association primary key (kind, label,
- * file_id, related_id).
+ * file_id, related_scope, related_id, related_ns, related_stack).
  */
 function associationEqual(a, b) {
     if (a.kind !== b.kind || a.label !== b.label)
         return false;
     if (a.kind === 'attachment' && b.kind === 'attachment')
         return a.fileId === b.fileId;
-    if (a.kind === 'relationship' && b.kind === 'relationship')
-        return a.recordId === b.recordId;
+    if (a.kind === 'relationship' && b.kind === 'relationship') {
+        return targetEqual(a.target, b.target);
+    }
     return true;
 }
+/** Structural equality per target arm — what dissociate() matches on. */
+export function targetEqual(a, b) {
+    if (a.scope !== b.scope)
+        return false;
+    if (a.scope === 'record' && b.scope === 'record') {
+        return a.recordId === b.recordId && (a.stackUrl ?? '') === (b.stackUrl ?? '');
+    }
+    if (a.scope === 'entity' && b.scope === 'entity')
+        return a.entityId === b.entityId;
+    if (a.scope === 'external' && b.scope === 'external')
+        return a.ns === b.ns && a.id === b.id;
+    return false;
+}
 function permissionEqual(a, b) {
     if (a.access !== b.access)
         return false;
@@ -2073,10 +2202,16 @@ const MAX_QUERY_LIMIT = 1000;
  */
 function stampGroupAdmin(associations, creator) {
     const list = associations ?? [];
-    const alreadyAdmin = list.some((a) => a.kind === 'relationship' && a.label === 'admin' && a.recordId === creator);
+    const alreadyAdmin = list.some((a) => a.kind === 'relationship' &&
+        a.label === 'admin' &&
+        a.target.scope === 'entity' &&
+        a.target.entityId === creator);
     if (alreadyAdmin)
         return list;
-    return [...list, { kind: 'relationship', label: 'admin', recordId: creator }];
+    return [
+        ...list,
+        { kind: 'relationship', label: 'admin', target: { scope: 'entity', entityId: creator } },
+    ];
 }
 /**
  * Drops a snapshot's `permissions` — owner-only audit data, never served
@@ -2198,6 +2333,8 @@ class ScopedSubscription extends Subscription {
     async filterAndDeliver(emission) {
         if (this.isClosed)
             return;
+        if (!passesUnlistedBoundary(emission, this.opts.includeUnlisted))
+            return;
         try {
             if (!(await this.canRead(emission.record, this.cache)))
                 return;
@@ -2583,10 +2720,15 @@ export class ScopedStack {
     }
     /**
      * Reference-creation gate for one association: `attachment` requires
-     * file access, `relationship` read access to its target; `tag` is
-     * unchecked, and `_group` roster associations are gated by the stricter
-     * isGroupManager() instead. See docs/spec/access-control.md
-     * § Reference-creation gating.
+     * 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.
      */
     async requireAssociationAccess(typeId, association) {
         if (association.kind === 'attachment') {
@@ -2594,7 +2736,14 @@ export class ScopedStack {
                 throw new StackPermissionError();
         }
         else if (association.kind === 'relationship' && baseIdOf(typeId) !== SYSTEM_TYPES.GROUP) {
-            if (!(await this.canReadReferent(association.recordId)))
+            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.scope !== 'record' || target.stackUrl)
+                return;
+            if (!(await this.canReadReferent(target.recordId)))
                 throw new StackPermissionError();
         }
     }
@@ -2626,6 +2775,9 @@ export class ScopedStack {
         if (opts.permissions?.length && !this.mayGrantAccess()) {
             throw new StackPermissionError('A delegated principal cannot set permissions, at create time or after');
         }
+        if (opts.unlisted && !this.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) {
@@ -2690,6 +2842,10 @@ export class ScopedStack {
      */
     async query(query = {}) {
         assertValidSort(query.sort);
+        assertValidRelatedTo(query.filter?.relatedTo);
+        if (query.filter?.includeUnlisted && !this.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;
@@ -2775,6 +2931,7 @@ export class ScopedStack {
             filter: {
                 baseId: SYSTEM_TYPES.APP,
                 includeDeleted: true,
+                includeUnlisted: true,
                 ...(this.stack.features.contentFieldQuery && {
                     content: { did: this.principalEntityId },
                 }),
@@ -2851,6 +3008,30 @@ export class ScopedStack {
         }
         return this.stack.setPermissions(id, permissions, { ...opts, ...this.actor });
     }
+    /**
+     * Withhold a record from enumeration, or restore it — gated exactly like
+     * setPermissions(), since both decide who or what can discover the
+     * record rather than merely read it once found. See
+     * docs/spec/access-control.md § Unlisted records.
+     */
+    async setUnlisted(id, unlisted, opts = {}) {
+        const record = await this.stack.get(id);
+        if (!record)
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        await this.requireOwnerForGrantRecord(record);
+        if (baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP) {
+            if (!this.isGroupManager(record))
+                throw await this.denialFor(record);
+        }
+        else {
+            if (!this.mayReshare(this.principalEntityId, record))
+                throw await this.denialFor(record);
+            if (this.delegated && !this.mayReshare(this.subjectEntityId, record)) {
+                throw await this.denialFor(record);
+            }
+        }
+        return this.stack.setUnlisted(id, unlisted, { ...opts, ...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
@@ -3032,6 +3213,9 @@ export class ScopedStack {
                 '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.');
         }
+        if (opts.includeUnlisted && !this.ownerActingAlone) {
+            throw new StackPermissionError('includeUnlisted is owner-only');
+        }
         return this.changes.add(new ScopedSubscription((record, cache) => this.canReadCached(record, cache), handler, opts));
     }
     /**