@haverstack/core 0.7.0 → 0.9.0

package/README.md

@@ -14,25 +14,36 @@ npm install @haverstack/core
 
 You'll also need a storage adapter:
 
-- [`@haverstack/adapter-sqlite`](https://www.npmjs.com/package/@haverstack/adapter-sqlite) — local SQLite storage via sql.js
+- [`@haverstack/adapter-local`](https://www.npmjs.com/package/@haverstack/adapter-local) — local storage (native SQLite + disk), single-app/embedded or server use
 
 ## Quick start
 
 ```ts
 import { Stack } from '@haverstack/core';
-import { SQLiteAdapter } from '@haverstack/adapter-sqlite';
-
-// First run — initialize a new stack
-const adapter = await SQLiteAdapter.initialize({
-  path: './my-stack.db',
-  entityId: 'my-entity-id',
+import { generateDidKeypair, exportDidPrivateKeyJwk } from '@haverstack/core/did';
+import { LocalAdapter } from '@haverstack/adapter-local';
+import { writeFile } from 'node:fs/promises';
+
+const dbPath = './my-stack.db';
+const keyPath = './my-stack.key.json'; // see "Key custody" below for where this really belongs
+
+// First run: neither file exists yet, so this generates an identity
+// keypair and persists the private key before initializing. Every run
+// after that: the db exists, so this just opens it — the entityId
+// function below is never called, so no throwaway keypair is minted.
+const adapter = await LocalAdapter.openOrInitialize({
+  path: dbPath,
   timezone: 'America/New_York',
+  entityId: async () => {
+    const { did, privateKey } = await generateDidKeypair();
+    await writeFile(keyPath, JSON.stringify(await exportDidPrivateKeyJwk(privateKey)));
+    return did;
+  },
 });
 
-// Subsequent runs — open the existing stack
-// const adapter = await SQLiteAdapter.open({ path: './my-stack.db' });
-
-const stack = await Stack.create(adapter);
+// ownerProfile creates your own _entity profile record on first run —
+// safe to keep passing on every open, it's a no-op once the record exists.
+const stack = await Stack.create(adapter, { ownerProfile: { name: 'Jane Smith' } });
 
 // Define a type
 await stack.defineType('com.example.myapp/note@1', 'Note', {
@@ -59,7 +70,6 @@ const notes = await stack.query({
 });
 
 // Tear down when done
-await stack.flush();
 await stack.close();
 ```
 
@@ -72,7 +82,13 @@ The fundamental unit of data. Every record has:
 - A **Crockford base-32 ID** — time-sortable, human-readable, URL-safe
 - A **type** — defined by the app that created it
 - **Content** — a JSON object validated against the type's schema
-- Optional: `parentId`, `entityId`, `appId`, `permissions`, `associations`
+- Optional: `parentId`, `entityId`, `appId`, `principalId`, `permissions`, `associations`
+
+### Identity
+
+`entityId` is a DID string (e.g. `did:key:z6Mk...`) — a keypair, not a name issued by any provider. `generateDidKeypair()` mints the mandatory floor method, `did:key`. `_entity` records are local profile cards _about_ a DID (`{ did, name, handle? }`), not the identity itself — the petname pattern. See [Identity](https://github.com/haverstack/core/blob/main/docs/spec/identity.md) in the spec.
+
+**Key custody.** Nothing in `@haverstack/core` or any adapter stores the `privateKey` — only the public `did` travels with stack data. Persisting it (JWK via `exportDidPrivateKeyJwk()`/`importDidPrivateKeyJwk()`, or the `CryptoKey` itself in a browser's IndexedDB) is on you. Losing it doesn't break anything local — but you can never again authenticate as that identity to a server, since `did:key` identity _is_ the key. See [Key custody](https://github.com/haverstack/core#key-custody) in the main README for per-platform recipes.
 
 ### Types
 
@@ -90,7 +106,7 @@ Tags, attachments, and relationships are unified under a single model:
 
 ```ts
 { kind: 'tag',          label: 'favourite' }
-{ kind: 'attachment',   label: 'avatar',   fileId: '...', mimeType: 'image/png' }
+{ kind: 'attachment',   label: 'avatar',   fileId: '...' }
 { kind: 'relationship', label: 'reply-to', recordId: '...' }
 ```
 

package/dist/access.d.ts

@@ -6,20 +6,33 @@
  * storage backend. Used by ScopedStack (see stack.ts) to enforce access
  * control; exported standalone for callers that want the raw predicate.
  */
-import type { RecordId, StackRecord } from './types.js';
+import type { Association, EntityId, RecordId, StackRecord } from './types.js';
 export type AccessMode = 'read' | 'write';
+/** An entity's standing within a `_group` Record's roster. `admin` implies `member` for ACL purposes. */
+export type GroupRole = 'member' | 'admin';
 /**
  * Resolves a Record by ID. Used to walk a `_group` Record's associations for
  * membership checks without requiring a full StackAdapter.
  */
 export type RecordResolver = (id: RecordId) => Promise<StackRecord | null>;
 /**
- * Check whether an entity has read or write access to a Record.
+ * Check whether an entity has read or write access to a Record: absent
+ * permissions = owner only; public = anyone reads; entity = direct match;
+ * group = walk the _group Record's roster associations. See
+ * docs/spec/access-control.md § Record-level permissions.
  *
- * - No permissions (absent/empty): owner only.
- * - public: anyone can read; write still requires an explicit grant.
- * - entity: direct entityId match.
- * - group: walk the _group Record's relationship associations for membership.
+ * The entity here is the **subject** — record-level permissions are written
+ * about who data is for, never about the software that carried the request.
+ * A delegated app's own authority is a separate question, asked of the
+ * principal. See docs/spec/access-control.md § Delegation: principal and
+ * subject.
  */
-export declare function checkAccess(record: StackRecord, requesterEntityId: string | null, ownerEntityId: string | null, mode: AccessMode, resolveRecord: RecordResolver): Promise<boolean>;
+export declare function checkAccess(record: StackRecord, subjectEntityId: EntityId | null, ownerEntityId: EntityId | null, mode: AccessMode, resolveRecord: RecordResolver): Promise<boolean>;
+/**
+ * Determine an entity's role within a `_group` Record's roster from its
+ * relationship associations. `admin` short-circuits — it's strictly more
+ * privileged than `member`, so a matching admin association wins regardless
+ * of association order.
+ */
+export declare function groupRoleFromAssociations(associations: Association[] | undefined, entityId: EntityId): GroupRole | null;
 //# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,IAAI,EAAE,UAAU,EAChB,aAAa,EAAE,cAAc,GAC5B,OAAO,CAAC,OAAO,CAAC,CA2BlB"}
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C,yGAAyG;AACzG,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,eAAe,EAAE,QAAQ,GAAG,IAAI,EAChC,aAAa,EAAE,QAAQ,GAAG,IAAI,EAC9B,IAAI,EAAE,UAAU,EAChB,aAAa,EAAE,cAAc,GAC5B,OAAO,CAAC,OAAO,CAAC,CA4BlB;AAYD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,WAAW,EAAE,GAAG,SAAS,EACvC,QAAQ,EAAE,QAAQ,GACjB,SAAS,GAAG,IAAI,CASlB"}

package/dist/access.js

@@ -7,16 +7,20 @@
  * control; exported standalone for callers that want the raw predicate.
  */
 /**
- * Check whether an entity has read or write access to a Record.
+ * Check whether an entity has read or write access to a Record: absent
+ * permissions = owner only; public = anyone reads; entity = direct match;
+ * group = walk the _group Record's roster associations. See
+ * docs/spec/access-control.md § Record-level permissions.
  *
- * - No permissions (absent/empty): owner only.
- * - public: anyone can read; write still requires an explicit grant.
- * - entity: direct entityId match.
- * - group: walk the _group Record's relationship associations for membership.
+ * The entity here is the **subject** — record-level permissions are written
+ * about who data is for, never about the software that carried the request.
+ * A delegated app's own authority is a separate question, asked of the
+ * principal. See docs/spec/access-control.md § Delegation: principal and
+ * subject.
  */
-export async function checkAccess(record, requesterEntityId, ownerEntityId, mode, resolveRecord) {
+export async function checkAccess(record, subjectEntityId, ownerEntityId, mode, resolveRecord) {
     // Owner always has full access.
-    if (requesterEntityId && requesterEntityId === ownerEntityId)
+    if (subjectEntityId && subjectEntityId === ownerEntityId)
         return true;
     const perms = record.permissions;
     // No permissions = private.
@@ -25,15 +29,16 @@ export async function checkAccess(record, requesterEntityId, ownerEntityId, mode
     for (const p of perms) {
         if (p.access === 'public' && mode === 'read')
             return true;
-        if (p.access === 'entity' && p.entityId === requesterEntityId) {
+        if (p.access === 'entity' && p.entityId === subjectEntityId) {
             if (mode === 'read' && p.read)
                 return true;
             if (mode === 'write' && p.write)
                 return true;
         }
-        if (p.access === 'group' && requesterEntityId) {
-            const member = await isGroupMember(p.groupId, requesterEntityId, resolveRecord);
-            if (member) {
+        if (p.access === 'group' && subjectEntityId) {
+            const role = await resolveGroupRole(p.groupId, subjectEntityId, resolveRecord);
+            const satisfiesRole = p.role === 'admin' ? role === 'admin' : role !== null;
+            if (satisfiesRole) {
                 if (mode === 'read' && p.read)
                     return true;
                 if (mode === 'write' && p.write)
@@ -43,12 +48,28 @@ export async function checkAccess(record, requesterEntityId, ownerEntityId, mode
     }
     return false;
 }
-async function isGroupMember(groupRecordId, entityId, resolveRecord) {
+async function resolveGroupRole(groupRecordId, entityId, resolveRecord) {
     const group = await resolveRecord(groupRecordId);
     if (!group)
-        return false;
-    return (group.associations ?? []).some((a) => a.kind === 'relationship' &&
-        (a.label === 'member' || a.label === 'admin') &&
-        a.recordId === entityId);
+        return null;
+    return groupRoleFromAssociations(group.associations, entityId);
+}
+/**
+ * Determine an entity's role within a `_group` Record's roster from its
+ * relationship associations. `admin` short-circuits — it's strictly more
+ * privileged than `member`, so a matching admin association wins regardless
+ * of association order.
+ */
+export function groupRoleFromAssociations(associations, entityId) {
+    let role = null;
+    for (const a of associations ?? []) {
+        if (a.kind === 'relationship' && a.recordId === entityId) {
+            if (a.label === 'admin')
+                return 'admin';
+            if (a.label === 'member')
+                role = 'member';
+        }
+    }
+    return role;
 }
 //# sourceMappingURL=access.js.map

package/dist/access.js.map

@@ -1 +1 @@
-{"version":3,"file":"access.js","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAmB,EACnB,iBAAgC,EAChC,aAA4B,EAC5B,IAAgB,EAChB,aAA6B;IAE7B,gCAAgC;IAChC,IAAI,iBAAiB,IAAI,iBAAiB,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IAE1E,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC;IAEjC,4BAA4B;IAC5B,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAE/C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QAE1D,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,iBAAiB,EAAE,CAAC;YAC9D,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC3C,IAAI,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;QAC/C,CAAC;QAED,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,IAAI,iBAAiB,EAAE,CAAC;YAC9C,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,CAAC,CAAC,OAAO,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAC;YAChF,IAAI,MAAM,EAAE,CAAC;gBACX,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI;oBAAE,OAAO,IAAI,CAAC;gBAC3C,IAAI,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,aAAuB,EACvB,QAAgB,EAChB,aAA6B;IAE7B,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,CAAC,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,IAAI,CACpC,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,KAAK,cAAc;QACzB,CAAC,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC;QAC7C,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAC1B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAmB,EACnB,eAAgC,EAChC,aAA8B,EAC9B,IAAgB,EAChB,aAA6B;IAE7B,gCAAgC;IAChC,IAAI,eAAe,IAAI,eAAe,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IAEtE,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC;IAEjC,4BAA4B;IAC5B,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAE/C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QAE1D,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,eAAe,EAAE,CAAC;YAC5D,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC3C,IAAI,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;QAC/C,CAAC;QAED,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,IAAI,eAAe,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,CAAC,CAAC,OAAO,EAAE,eAAe,EAAE,aAAa,CAAC,CAAC;YAC/E,MAAM,aAAa,GAAG,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;YAC5E,IAAI,aAAa,EAAE,CAAC;gBAClB,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI;oBAAE,OAAO,IAAI,CAAC;gBAC3C,IAAI,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,gBAAgB,CAC7B,aAAuB,EACvB,QAAkB,EAClB,aAA6B;IAE7B,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,yBAAyB,CAAC,KAAK,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,YAAuC,EACvC,QAAkB;IAElB,IAAI,IAAI,GAAqB,IAAI,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,YAAY,IAAI,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACzD,IAAI,CAAC,CAAC,KAAK,KAAK,OAAO;gBAAE,OAAO,OAAO,CAAC;YACxC,IAAI,CAAC,CAAC,KAAK,KAAK,QAAQ;gBAAE,IAAI,GAAG,QAAQ,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/adapter-entry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @haverstack/core/adapter
+ * -------------------------------------------------------
+ * The interfaces a storage adapter implements — record storage, blob
+ * storage, and the capabilities an adapter declares. Audience: adapter
+ * implementers (see the in-repo adapters), not app or plugin code, which
+ * reads `stack.features` instead of these directly.
+ */
+export type { StackRecordAdapter, StackBlobAdapter, AdapterCapabilities, BlobFileInfo, ExpectedVersionOptions, } from './types.js';
+export { combineAdapters } from './combine.js';
+export { assertQueryCapabilities } from './stack.js';
+//# sourceMappingURL=adapter-entry.d.ts.map

package/dist/adapter-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-entry.d.ts","sourceRoot":"","sources":["../src/adapter-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,YAAY,EACZ,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

package/dist/adapter-entry.js

@@ -0,0 +1,11 @@
+/**
+ * @haverstack/core/adapter
+ * -------------------------------------------------------
+ * The interfaces a storage adapter implements — record storage, blob
+ * storage, and the capabilities an adapter declares. Audience: adapter
+ * implementers (see the in-repo adapters), not app or plugin code, which
+ * reads `stack.features` instead of these directly.
+ */
+export { combineAdapters } from './combine.js';
+export { assertQueryCapabilities } from './stack.js';
+//# sourceMappingURL=adapter-entry.js.map

package/dist/adapter-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-entry.js","sourceRoot":"","sources":["../src/adapter-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

package/dist/attachment-download.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Stack — Attachment Download Content-Type Resolution
+ * -------------------------------------------------------
+ * Shared, pure implementation of the `GET /attachments/:fileId` dangerous-
+ * type policy (docs/spec/wire-format.md § Download). Core has no HTTP
+ * server of its own — this module exists so `haverstack/server` and any
+ * other server implementation share one safe-list and one forcing
+ * computation, rather than each re-deriving it and risking drift on a
+ * security-relevant policy (the same "written once, not a per-server
+ * convention" principle applied elsewhere to adapter invariants).
+ *
+ * The policy is result-not-source: `resolveAttachmentDownloadContentType()`
+ * computes a single candidate type from whichever source wins (explicit
+ * param, then filename extension, then stored metadata, then
+ * application/octet-stream) and applies the safe-list to *that value* —
+ * never to the source that produced it, so no source can route a
+ * dangerous type past the check.
+ */
+/** application/octet-stream: the forced replacement for any unsafe type. */
+export declare const FORCED_CONTENT_TYPE = "application/octet-stream";
+export declare const NOSNIFF_HEADER_NAME = "X-Content-Type-Options";
+export declare const NOSNIFF_HEADER_VALUE = "nosniff";
+/**
+ * Whether a MIME type may be served as-is (Content-Type set to it, no
+ * forced download). Checked against the normalized base type — any
+ * parameters or casing on the input don't affect the result.
+ */
+export declare function isSafeAttachmentContentType(mimeType: string): boolean;
+/** Infers a candidate MIME type from a filename's extension. Returns undefined for no extension or an unrecognized one — the caller falls through to the next source. */
+export declare function inferContentTypeFromFilename(filename: string): string | undefined;
+/**
+ * Which `_attachment@1` record establishes a fileId's mimeType — the
+ * "first-recorded" rule of docs/spec/attachments.md, as a total order:
+ * earliest `createdAt`, ties broken by the lower `id`.
+ *
+ * The tiebreak is what makes it a rule rather than a coincidence of scan
+ * order. Rejecting a conflicting mimeType at write time is check-then-act
+ * with no storage-level uniqueness behind it, so two racing first uploads
+ * of the same bytes can both land on a concurrent server. Determinism
+ * doesn't depend on that never happening — it depends on every reader
+ * ordering the records the same way, which is why core's write-time
+ * conflict check and a server's serving choice both come through here.
+ *
+ * Generic over the record shape so a server can pass its own row type.
+ * Records for other fileIds must be filtered out by the caller.
+ */
+export declare function firstRecordedAttachment<T extends {
+    id: string;
+    createdAt: Date;
+}>(records: readonly T[]): T | undefined;
+export type AttachmentDownloadContentType = {
+    /** The Content-Type header value to serve. */
+    contentType: string;
+    /**
+     * Whether the dangerous-type policy overrode the candidate. When true,
+     * the server MUST also force `Content-Disposition: attachment` — Content-
+     * Type forcing alone doesn't stop a browser from sniffing the body back
+     * into the original type without both nosniff (always required, see
+     * NOSNIFF_HEADER_NAME/VALUE) and a non-inline disposition.
+     */
+    forced: boolean;
+};
+/**
+ * Resolve the Content-Type served for `GET /attachments/:fileId`
+ * (docs/spec/wire-format.md § Download): `?contentType` wins, else
+ * extension inference from `?filename`, else the stored mimeType, else
+ * `application/octet-stream` — then the safe-list is applied to whichever
+ * candidate that produced.
+ */
+export declare function resolveAttachmentDownloadContentType(input: {
+    contentTypeParam?: string;
+    filenameParam?: string;
+    storedMimeType?: string;
+}): AttachmentDownloadContentType;
+//# sourceMappingURL=attachment-download.d.ts.map

package/dist/attachment-download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-download.d.ts","sourceRoot":"","sources":["../src/attachment-download.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAcH,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,6BAA6B,CAAC;AAE9D,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAC5D,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAO9C;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKrE;AAmCD,yKAAyK;AACzK,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,EAC/E,OAAO,EAAE,SAAS,CAAC,EAAE,GACpB,CAAC,GAAG,SAAS,CAOf;AAED,MAAM,MAAM,6BAA6B,GAAG;IAC1C,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAAC,KAAK,EAAE;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,6BAA6B,CAUhC"}

package/dist/attachment-download.js

@@ -0,0 +1,128 @@
+/**
+ * Stack — Attachment Download Content-Type Resolution
+ * -------------------------------------------------------
+ * Shared, pure implementation of the `GET /attachments/:fileId` dangerous-
+ * type policy (docs/spec/wire-format.md § Download). Core has no HTTP
+ * server of its own — this module exists so `haverstack/server` and any
+ * other server implementation share one safe-list and one forcing
+ * computation, rather than each re-deriving it and risking drift on a
+ * security-relevant policy (the same "written once, not a per-server
+ * convention" principle applied elsewhere to adapter invariants).
+ *
+ * The policy is result-not-source: `resolveAttachmentDownloadContentType()`
+ * computes a single candidate type from whichever source wins (explicit
+ * param, then filename extension, then stored metadata, then
+ * application/octet-stream) and applies the safe-list to *that value* —
+ * never to the source that produced it, so no source can route a
+ * dangerous type past the check.
+ */
+/** MIME types that pass through unforced, regardless of source. */
+const SAFE_EXACT_TYPES = new Set(['application/pdf', 'text/plain', 'application/octet-stream']);
+/** MIME type prefixes that pass through unforced, except for UNSAFE_OVERRIDES below. */
+const SAFE_PREFIXES = ['image/', 'video/', 'audio/'];
+/**
+ * Matches a SAFE_PREFIXES entry but is script-capable and must still be
+ * forced — image/svg+xml is the reason a plain prefix check isn't enough.
+ */
+const UNSAFE_OVERRIDES = new Set(['image/svg+xml']);
+/** application/octet-stream: the forced replacement for any unsafe type. */
+export const FORCED_CONTENT_TYPE = 'application/octet-stream';
+export const NOSNIFF_HEADER_NAME = 'X-Content-Type-Options';
+export const NOSNIFF_HEADER_VALUE = 'nosniff';
+/** Strips MIME parameters ("text/html; charset=utf-8" -> "text/html") and lowercases, so parameter tricks and casing can't bypass the safe-list check. */
+function normalizeMimeType(mimeType) {
+    return mimeType.split(';')[0].trim().toLowerCase();
+}
+/**
+ * Whether a MIME type may be served as-is (Content-Type set to it, no
+ * forced download). Checked against the normalized base type — any
+ * parameters or casing on the input don't affect the result.
+ */
+export function isSafeAttachmentContentType(mimeType) {
+    const normalized = normalizeMimeType(mimeType);
+    if (UNSAFE_OVERRIDES.has(normalized))
+        return false;
+    if (SAFE_EXACT_TYPES.has(normalized))
+        return true;
+    return SAFE_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+/**
+ * Extension -> candidate MIME type, used only when resolving from a
+ * `?filename` param with no explicit `?contentType` (spec: extension
+ * inference). Deliberately includes dangerous types (html, svg, js, xml)
+ * — forcing applies to the computed candidate, not to how it was computed,
+ * so listing them here is what lets the safe-list catch them.
+ */
+const EXTENSION_MIME_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    bmp: 'image/bmp',
+    avif: 'image/avif',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mov: 'video/quicktime',
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    pdf: 'application/pdf',
+    txt: 'text/plain',
+    html: 'text/html',
+    htm: 'text/html',
+    xhtml: 'application/xhtml+xml',
+    svg: 'image/svg+xml',
+    js: 'text/javascript',
+    mjs: 'text/javascript',
+    xml: 'application/xml',
+    xsl: 'text/xsl',
+};
+/** Infers a candidate MIME type from a filename's extension. Returns undefined for no extension or an unrecognized one — the caller falls through to the next source. */
+export function inferContentTypeFromFilename(filename) {
+    const match = /\.([a-z0-9]+)$/i.exec(filename);
+    return match ? EXTENSION_MIME_TYPES[match[1].toLowerCase()] : undefined;
+}
+/**
+ * Which `_attachment@1` record establishes a fileId's mimeType — the
+ * "first-recorded" rule of docs/spec/attachments.md, as a total order:
+ * earliest `createdAt`, ties broken by the lower `id`.
+ *
+ * The tiebreak is what makes it a rule rather than a coincidence of scan
+ * order. Rejecting a conflicting mimeType at write time is check-then-act
+ * with no storage-level uniqueness behind it, so two racing first uploads
+ * of the same bytes can both land on a concurrent server. Determinism
+ * doesn't depend on that never happening — it depends on every reader
+ * ordering the records the same way, which is why core's write-time
+ * conflict check and a server's serving choice both come through here.
+ *
+ * Generic over the record shape so a server can pass its own row type.
+ * Records for other fileIds must be filtered out by the caller.
+ */
+export function firstRecordedAttachment(records) {
+    return records.reduce((first, record) => {
+        if (!first)
+            return record;
+        const delta = record.createdAt.getTime() - first.createdAt.getTime();
+        if (delta !== 0)
+            return delta < 0 ? record : first;
+        return record.id < first.id ? record : first;
+    }, undefined);
+}
+/**
+ * Resolve the Content-Type served for `GET /attachments/:fileId`
+ * (docs/spec/wire-format.md § Download): `?contentType` wins, else
+ * extension inference from `?filename`, else the stored mimeType, else
+ * `application/octet-stream` — then the safe-list is applied to whichever
+ * candidate that produced.
+ */
+export function resolveAttachmentDownloadContentType(input) {
+    const candidate = input.contentTypeParam ||
+        (input.filenameParam && inferContentTypeFromFilename(input.filenameParam)) ||
+        input.storedMimeType ||
+        FORCED_CONTENT_TYPE;
+    return isSafeAttachmentContentType(candidate)
+        ? { contentType: candidate, forced: false }
+        : { contentType: FORCED_CONTENT_TYPE, forced: true };
+}
+//# sourceMappingURL=attachment-download.js.map

package/dist/attachment-download.js.map

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

package/dist/auth.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Stack — Authentication handshake primitives
+ * -------------------------------------------------------
+ * The challenge–response handshake proves a client holds the key behind a
+ * DID, so a server can issue it a bearer token without an out-of-band
+ * secret handoff. See docs/spec/wire-format.md § Authentication.
+ *
+ * What lives here is the half both sides must agree on byte for byte: the
+ * payload that gets signed. A client builds it to sign; a server builds it
+ * to verify. Two implementations of "the same string" would diverge on the
+ * first ambiguity, and the failure mode is a signature that verifies
+ * against a payload nobody meant — so there is one constructor, exported,
+ * the same way the attachment content-type policy is shared rather than
+ * re-derived.
+ *
+ * Core verifies signatures; it does not run a server. Nonce storage,
+ * single-use enforcement and token issuance are the server's.
+ */
+import { type DidKeypair } from './did.js';
+/**
+ * Malformed input to a handshake primitive — a bad origin, DID, or nonce,
+ * caught locally before anything is signed or verified. Outside the
+ * StackError hierarchy, like InvalidDidError: no Stack operation has begun,
+ * so there is no wire code or status to carry (docs/spec/wire-format.md
+ * § The taxonomy root).
+ */
+export declare class InvalidAuthChallengeError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Domain-separation tag. Version it rather than the payload's shape: a
+ * future signing primitive picks its own tag, so no signature made for one
+ * purpose can ever verify as another.
+ */
+export declare const AUTH_PAYLOAD_LABEL = "haverstack-auth-v1";
+export type AuthChallenge = {
+    /** The server's own public origin, e.g. "https://stack.example.com". */
+    origin: string;
+    /** The DID being proven. */
+    did: string;
+    /** The nonce the server issued for this DID. */
+    nonce: string;
+};
+/**
+ * Reduce a URL to the origin form the payload uses: scheme, host and a
+ * non-default port. A client derives it from the URL it dialed; a server
+ * MUST derive it from its own configured public origin rather than from a
+ * request header, which a client controls.
+ */
+export declare const authOriginFromUrl: (url: string) => string;
+/**
+ * Build the exact bytes a client signs and a server verifies.
+ *
+ * The origin is in the payload because the nonce alone doesn't scope a
+ * signature to a server: one that a client connects to can fetch a
+ * challenge from the client's real stack, pass that nonce along, and
+ * redeem the returned signature as a token. Signing the origin the client
+ * believes it is talking to makes such a signature verify nowhere else.
+ */
+export declare const buildAuthChallengePayload: (challenge: AuthChallenge) => Uint8Array;
+/** Sign a challenge with the private key behind its DID. */
+export declare const signAuthChallenge: (privateKey: CryptoKey, challenge: AuthChallenge) => Promise<Uint8Array>;
+/**
+ * Verify a challenge signature. Answers only "this signature was made by
+ * the key behind this DID, for this origin and nonce" — whether the nonce
+ * was ever issued, is unexpired, and has not already been spent is the
+ * server's to track, and all three matter.
+ */
+export declare const verifyAuthChallenge: (challenge: AuthChallenge, signature: Uint8Array) => Promise<boolean>;
+/**
+ * What a client hands an adapter to authenticate: a DID and a signing
+ * callback, never a private key. Key custody stays with the app (see
+ * docs/spec/identity.md), so a caller is free to back this with a hardware
+ * key, an OS keychain, or a prompt.
+ */
+export type DidCredential = {
+    did: string;
+    sign: (payload: Uint8Array) => Promise<Uint8Array>;
+};
+/**
+ * Build a credential from a keypair, for callers holding key material in
+ * process and wanting no ceremony. Anything else implements DidCredential
+ * directly.
+ */
+export declare const didCredentialFromKeypair: (keypair: DidKeypair) => DidCredential;
+export declare const base64urlEncode: (bytes: Uint8Array) => string;
+export declare const base64urlDecode: (encoded: string) => Uint8Array;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAA+C,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAMxF;;;;;;GAMG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,SAAK;CAIzB;AAMD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AASvD,MAAM,MAAM,aAAa,GAAG;IAC1B,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,MAa/C,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAI,WAAW,aAAa,KAAG,UAapE,CAAC;AAMF,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,GAC5B,YAAY,SAAS,EACrB,WAAW,aAAa,KACvB,OAAO,CAAC,UAAU,CAAkE,CAAC;AAExF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,WAAW,aAAa,EACxB,WAAW,UAAU,KACpB,OAAO,CAAC,OAAO,CASjB,CAAC;AAMF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACpD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,UAAU,KAAG,aAG7D,CAAC;AAMH,eAAO,MAAM,eAAe,GAAI,OAAO,UAAU,KAAG,MAInD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,UAYjD,CAAC"}