@haverstack/server 0.8.0

package/Dockerfile

@@ -0,0 +1,30 @@
+# deps: install production dependencies only
+FROM node:22-slim AS deps
+RUN npm install -g pnpm@10
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+RUN pnpm install --frozen-lockfile --prod
+
+# builder: compile TypeScript
+FROM node:22-slim AS builder
+RUN npm install -g pnpm@10
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.json tsconfig.build.json ./
+RUN pnpm install --frozen-lockfile
+COPY src ./src
+RUN pnpm build
+
+# runner: minimal production image
+FROM node:22-slim AS runner
+RUN groupadd -r app && useradd -r -g app app
+WORKDIR /app
+COPY --from=deps --chown=app:app /app/node_modules ./node_modules
+COPY --from=builder --chown=app:app /app/dist ./dist
+COPY --from=builder --chown=app:app /app/package.json ./
+RUN mkdir -p /app/data && chown app:app /app/data
+VOLUME ["/app/data"]
+ENV NODE_ENV=production
+ENV DB_PATH=/app/data/stack.db
+EXPOSE 3000
+USER app
+CMD ["node", "dist/index.js"]

package/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/README.md

@@ -0,0 +1,107 @@
+# Haverstack Server
+
+Reference HTTP server implementation for [Haverstack](https://github.com/haverstack/core).
+
+Exposes a Haverstack stack over a REST API so apps can read and write records remotely. Uses SQLite for storage via `@haverstack/adapter-local`.
+
+> **Status:** Early development. APIs are unstable.
+
+---
+
+## Quick start
+
+```sh
+cp .env.example .env
+# Edit .env — set OWNER_TOKEN, ENTITY_ID, and BASE_URL at minimum
+pnpm install
+pnpm dev
+```
+
+The server listens on `PORT` (default `3000`). On first run it initializes a new SQLite database at `DB_PATH`.
+
+---
+
+## Docker
+
+```sh
+docker run -d \
+  -e OWNER_TOKEN=<secret> \
+  -e ENTITY_ID=<your-entity-id> \
+  -e BASE_URL=https://stack.example.com \
+  -p 3000:3000 \
+  -v haverstack-data:/app/data \
+  ghcr.io/haverstack/server:latest
+```
+
+`/app/data` holds the SQLite database, its WAL sidecar files (`stack.db-wal`, `stack.db-shm`), a storage-ownership lock file (`stack.db.lock`), and attachments — mount a volume there for persistence. Set `ENTITY_ID` only on first run; it is ignored once the database exists, though a value that no longer matches the stack's stored owner logs a startup warning rather than failing silently.
+
+Only one server process may hold a given `DB_PATH` at a time: a second process against the same path fails at startup with a clear error rather than silently sharing (or corrupting) the database. This is enforced by the storage adapter, independent of any reverse proxy or orchestrator setting — see [Deployment: single-writer topology](./docs/deployment.md#single-writer-topology).
+
+---
+
+## Configuration
+
+All configuration is via environment variables. See `.env.example` for the full list.
+
+| Variable                 | Required  | Default                                      | Description                                                                                                                                                                                                                                 |
+| ------------------------ | --------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OWNER_TOKEN`            | Yes       | —                                            | Break-glass bearer token for the stack owner. Treat like a password.                                                                                                                                                                        |
+| `ENTITY_ID`              | First run | —                                            | Owner entity ID — must be a DID (e.g. `did:key:z6Mk...`). Only needed when initializing a new DB.                                                                                                                                           |
+| `OWNER_NAME`             | No        | —                                            | Owner's display name. When set, ensures the owner's `_entity` profile record exists.                                                                                                                                                        |
+| `OWNER_HANDLE`           | No        | —                                            | Owner's handle. Only used alongside `OWNER_NAME`.                                                                                                                                                                                           |
+| `DB_PATH`                | No        | `/app/data/stack.db` (Docker) / `./stack.db` | Path to the SQLite database file.                                                                                                                                                                                                           |
+| `PORT`                   | No        | `3000`                                       | Port to listen on.                                                                                                                                                                                                                          |
+| `TIMEZONE`               | No        | — (none)                                     | IANA timezone. Only used on first run; omitted from discovery when unset.                                                                                                                                                                   |
+| `CORS_ORIGINS`           | No        | `` (none)                                    | Allowed origins, comma-separated or `*`.                                                                                                                                                                                                    |
+| `BASE_URL`               | Yes       | —                                            | Canonical public base URL of this server. Signed/verified against by the DID challenge-response handshake — see [API reference](./docs/api.md#authentication).                                                                              |
+| `MAX_ATTACHMENT_BYTES`   | No        | `52428800` (50 MB)                           | Maximum attachment upload size.                                                                                                                                                                                                             |
+| `MAX_CONTENT_BYTES`      | No        | `1048576` (1 MB)                             | Maximum JSON request body size (records, patches, etc). See [Deployment: request body size limits](./docs/deployment.md#request-body-size-limits).                                                                                          |
+| `QUERY_TIMEOUT_MS`       | No        | `10000` (10s)                                | Execution deadline for a `GET /records` or `POST /records/query` search, timed from when it reaches a worker. Exceeding it answers `503` (code `timeout`). See [Deployment: bounding query cost](./docs/deployment.md#bounding-query-cost). |
+| `QUERY_WORKER_POOL_SIZE` | No        | `2`                                          | Number of worker threads a slow search can run on without blocking other requests (max 32). See [Deployment: bounding query cost](./docs/deployment.md#bounding-query-cost).                                                                |
+| `QUERY_QUEUE_LIMIT`      | No        | `64`                                         | Searches allowed to queue for a worker before the server sheds load with `503` (code `timeout`). See [Deployment: bounding query cost](./docs/deployment.md#bounding-query-cost).                                                           |
+| `SEED_COMMONS_TYPES`     | No        | `false`                                      | Registers the [Schema Commons](https://github.com/haverstack/core/blob/main/docs/commons/README.md) types from `@haverstack/commons` on startup. See [Deployment: Schema Commons seeding](./docs/deployment.md#schema-commons-seeding).     |
+| `SHUTDOWN_TIMEOUT_MS`    | No        | `10000` (10s)                                | How long shutdown waits for open connections to drain before forcing them closed and finishing cleanup anyway.                                                                                                                              |
+
+---
+
+## Development
+
+```sh
+pnpm install
+pnpm dev              # Start with live reload
+pnpm test             # Run tests
+pnpm typecheck        # Type check
+pnpm lint             # Lint
+pnpm format:check     # Check formatting
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full pre-push checklist, where to file what, and the comment, commit, and architecture conventions this codebase follows. [AGENTS.md](./AGENTS.md) is the same material in condensed form, for AI coding agents.
+
+Releases are automatic: [Conventional Commits](https://www.conventionalcommits.org/) since the last tag decide the version bump, and every push to `main` bumps `package.json`, publishes the `ghcr.io/haverstack/server` image, tags, and cuts a GitHub release. See [CONTRIBUTING.md § Releasing](./CONTRIBUTING.md#releasing).
+
+---
+
+## Docs
+
+- [API reference](./docs/api.md) — routes, auth, and permissions
+- [Deployment guide](./docs/deployment.md) — TLS, CORS, and rate limiting
+- [Contributing](./CONTRIBUTING.md) — setup, conventions, and releases
+- [Security policy](./SECURITY.md) — reporting, scope, and documented non-vulnerabilities
+
+---
+
+## Security
+
+Found a weakness? Report it privately through [GitHub Security Advisories](https://github.com/haverstack/server/security/advisories/new). [SECURITY.md](./SECURITY.md) says what's in scope, which properties are documented decisions rather than bugs, and when a finding belongs in [`haverstack/core`](https://github.com/haverstack/core) instead — which is where to send anything you can't confidently place.
+
+---
+
+## Related
+
+- [`haverstack/core`](https://github.com/haverstack/core) — core library, types, adapters, and spec
+
+---
+
+## License
+
+[CC0 1.0 Universal](./LICENSE) — public domain. No rights reserved.

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security Policy
+
+This server holds someone's personal data and the tokens that speak for them. It is also the only place the Haverstack permission model is actually enforced — everything behind it is full trust. This document says what to do when you find a weakness, which repository to report it to, and which parts of the system carry a security promise at all.
+
+## Reporting a vulnerability
+
+**Report privately, through [GitHub Security Advisories](https://github.com/haverstack/server/security/advisories/new).** That opens a channel visible only to you and the maintainers. Please don't open a public issue or PR for a suspected vulnerability — a public report is a disclosure, and it lands before there's anything to upgrade to.
+
+Include what you have: the version or commit (`GET /.well-known/stack` and the image tag both name it), the request that triggers it, what an attacker gets, and the smallest reproduction you can manage. A failing test against `tests/routes/` is the most useful form, but prose is fine — a clear description of the wrong behavior beats a polished exploit.
+
+Expect an acknowledgement within a week. If a report is valid, you'll get the fix plan and the release it lands in; if it isn't, you'll get the reasoning, which is often the more interesting answer. Credit in the advisory unless you'd rather not be named.
+
+Nothing here is a bug bounty — this is a public-domain project with no budget behind it.
+
+## Which repository
+
+This repository is one implementation of a contract that lives elsewhere. The split matters for a report, because a fix in the wrong place leaves every other implementation exposed:
+
+- **Here** — a finding that is this server's alone: a route that enforces a permission incorrectly, a token that outlives its revocation, a header this server sets, a config default that is unsafe, something in the published Docker image.
+- **[`haverstack/core`](https://github.com/haverstack/core/security/advisories/new)** — a finding in the contract or the libraries: the access-control model itself, DID verification, the wire format, the error taxonomy, or anything in `@haverstack/core`, `@haverstack/adapter-local`, or `@haverstack/wire-types`. A bug there is a bug in every server and client at once.
+
+**When it isn't clear which side a finding sits on, report it to core** and say so. A weakness that reaches through this server into the permission model, a wire shape, or a signature check is nearly always the more serious of the two readings, and core is where the people who can adjudicate that are looking. The reverse mistake — filing a protocol-level flaw against one implementation — gets it fixed in one place and quietly leaves it standing everywhere else. Cross-repository advisories are routine; nobody will mind the reroute.
+
+## What is in scope
+
+The server in this repository, its default configuration (`.env.example`), and the `ghcr.io/haverstack/server` image built from it.
+
+**Especially interesting**, because they're where a mistake is least visible:
+
+- Any request that reads or writes a record the [permission rules](./docs/api.md#permissions) say it cannot — particularly through delegation, where effective authority is the intersection of the principal's and the subject's, or through a query filter that leaks a record the same caller couldn't fetch by id.
+- A response that discloses whether a record exists to a caller who couldn't read it — a `404` and a `403` that differ where they shouldn't, or a total count that changes.
+- Anything that lets a bearer token outlive its revocation or expiry, cross between principal and subject, or be minted for a DID the caller doesn't hold the key for: a challenge redeemable more than once, a nonce accepted after its window, a signature that verifies against a different `BASE_URL`.
+- An attachment served with a `Content-Type` or `Content-Disposition` that lets a browser execute it, or an attachment path that escapes its blob directory.
+- Input that reaches SQL as syntax rather than as a bound parameter, or that escapes the [error taxonomy](./docs/api.md#auth-errors) as a raw engine error with a stack trace or a filesystem path in it.
+- Anything that lets an unauthenticated caller consume resources without bound in a way the [query worker pool](./docs/deployment.md#bounding-query-cost) doesn't already cap — the deadline and queue limit are the intended bound, so a way around _them_ is a finding.
+- Secrets in the wrong place: `OWNER_TOKEN` or a session token in a log line, an error body, or an image layer.
+
+## What is not a vulnerability
+
+These are documented properties, not oversights. Each is a design decision with its reasoning in the docs; argue with the decision by opening an issue, not an advisory.
+
+- **The DID handshake is open.** `POST /auth/challenge` and `POST /auth/token` are unauthenticated: anyone reachable can generate a keypair and obtain a token for the `did:key` it derives. That is the point — the handshake proves _which_ DID is calling and authorizes nothing on its own. See [Deployment § The DID handshake is open by design](./docs/deployment.md#the-did-handshake-is-open-by-design).
+- **A grant with no grantee is a grant to the public**, and with the handshake open that means anyone. It is the documented meaning of `grant(null, ...)`, not a bypass. See [API § Permissions](./docs/api.md#permissions).
+- **`GET /.well-known/stack` is public** and exposes the owner entity ID, timezone, and capability list. Clients need it to bootstrap. A private stack restricts it by network policy, not by auth. See [Deployment § Public endpoints](./docs/deployment.md#public-endpoints).
+- **Read routes serve anonymous callers.** `GET /records`, `POST /records/query`, `GET /records/:id`, and `GET /types` answer without a token, subject to record-level permissions. A token changes who you are, not whether the route responds.
+- **Rate limiting and abuse control belong to the reverse proxy.** The server bounds query _cost_ (`QUERY_TIMEOUT_MS`, `QUERY_WORKER_POOL_SIZE`, `QUERY_QUEUE_LIMIT`) and body _size_ (`MAX_CONTENT_BYTES`, `MAX_ATTACHMENT_BYTES`), and deliberately does not implement request rate limiting. A deployment without a proxy limit is a misconfiguration; the guide gives Caddy, nginx, and Traefik configs. See [Deployment](./docs/deployment.md).
+- **TLS terminates upstream.** The server speaks plain HTTP and expects a proxy in front. Running it directly on a public port is a deployment error.
+- **`OWNER_TOKEN` is a shared secret with full owner authority** and no expiry. Treat it like a password; it is break-glass access, not a session.
+- **One process per `DB_PATH`.** Permissions exist only behind this server process, so a second writer would be a second, unenforced trust boundary — which is why starting one fails loudly. Direct access to `stack.db` by anything else is full trust by construction. See [Deployment § Single-writer topology](./docs/deployment.md#single-writer-topology).
+- **A lost `did:key` private key is unrecoverable**, and key rotation is deferred. That is a protocol property; see core's [Identity](https://github.com/haverstack/core/blob/main/docs/spec/identity.md) spec.
+
+## Supported versions
+
+This server is `0.x` and its API is unstable. Fixes land on `main` and ship in the next release, as a tag and a `ghcr.io/haverstack/server` image; there are no maintained release branches and no backports to older minors. `:latest` tracks the newest release. The practical advice is to track it, and to pin a digest only if you also watch for advisories.