@sovereignfs/create 0.18.0 → 0.27.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -3
- package/dist/create.mjs +354 -87
- package/package.json +3 -2
- package/template/app/AGENTS.md +36 -3
- package/template/app/CONTRIBUTING.md +3 -3
- package/template/app/Dockerfile +6 -5
- package/template/app/README.md +64 -32
- package/template/app/_env.example +11 -1
- package/template/app/_githooks/pre-push +2 -2
- package/template/app/_github/workflows/ci.yml +5 -4
- package/template/app/_github/workflows/publish.yml +8 -6
- package/template/app/_gitignore +4 -0
- package/template/app/app/actions.ts +34 -8
- package/template/app/app/api/auth/[...all]/route.ts +10 -0
- package/template/app/app/api/files/[id]/route.ts +4 -6
- package/template/app/app/api/files/route.ts +8 -5
- package/template/app/app/api/push/subscription/route.ts +23 -0
- package/template/app/app/api/sign-in-salt/route.ts +9 -0
- package/template/app/app/api/sovereign/account-deleted/route.ts +10 -0
- package/template/app/app/api/sovereign/backchannel-logout/route.ts +10 -0
- package/template/app/app/api/sovereign/export/route.ts +10 -0
- package/template/app/app/notifications.tsx +42 -0
- package/template/app/app/page.tsx +21 -9
- package/template/app/app/push-actions.ts +41 -0
- package/template/app/app/security/actions.ts +45 -0
- package/template/app/app/security/page.tsx +33 -0
- package/template/app/app/security/panels.tsx +50 -0
- package/template/app/app/sign-in/page.tsx +49 -0
- package/template/app/app/sign-in/panel.tsx +71 -0
- package/template/app/app/sign-out.tsx +19 -0
- package/template/app/app/sign-up/page.tsx +39 -0
- package/template/app/app/sign-up/panel.tsx +54 -0
- package/template/app/app/sw.js/route.ts +10 -2
- package/template/app/app/ui.tsx +13 -1
- package/template/app/compose.yml +3 -2
- package/template/app/instrumentation.ts +9 -1
- package/template/app/lib/account.ts +6 -0
- package/template/app/lib/crypto.ts +16 -9
- package/template/app/lib/csp.ts +5 -3
- package/template/app/lib/notices.ts +63 -0
- package/template/app/lib/push.ts +227 -0
- package/template/app/lib/session.ts +40 -0
- package/template/app/lib/sign-in-client.ts +22 -0
- package/template/app/lib/sign-in.ts +113 -0
- package/template/app/lib/sovereign.ts +12 -3
- package/template/app/migrations/002_push.sql +24 -0
- package/template/app/sovereign.manifest.json +11 -8
- package/template/encryption/_env.example +27 -0
- package/template/encryption/_skip +18 -0
- package/template/encryption/app/api/files/[id]/route.ts +45 -0
- package/template/encryption/app/api/files/route.ts +43 -0
- package/template/{app → encryption}/app/auth/[action]/route.ts +2 -1
- package/template/encryption/app/page.tsx +7 -2
- package/template/encryption/app/sign-out.tsx +21 -0
- package/template/encryption/app/ui.tsx +1 -0
- package/template/encryption/instrumentation.ts +12 -0
- package/template/encryption/lib/account.ts +6 -0
- package/template/encryption/lib/auth.ts +36 -0
- package/template/encryption/sovereign.manifest.json +4 -3
- package/template/pm/yarn/_yarnrc.yml +3 -0
- package/template/app/lib/auth.ts +0 -18
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sovereignfs/create",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.27.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "npm create @sovereignfs: makes an instance repository, pinned to the toolkit (sv) of the same version.",
|
|
6
6
|
"license": "AGPL-3.0-or-later",
|
|
@@ -24,7 +24,8 @@
|
|
|
24
24
|
"node": ">=24.15"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
|
-
"@sovereignfs/
|
|
27
|
+
"@sovereignfs/push": "0.2.0",
|
|
28
|
+
"@sovereignfs/pwa": "0.2.0",
|
|
28
29
|
"@sovereignfs/tsconfig": "0.0.0",
|
|
29
30
|
"@types/node": "^24.19.2",
|
|
30
31
|
"@types/semver": "^7.8.0",
|
package/template/app/AGENTS.md
CHANGED
|
@@ -31,16 +31,49 @@ this app's own; the shared one is written by `npm create @sovereignfs app sync`
|
|
|
31
31
|
- **A version is set with its changelog section,** in the same change: `version` in `package.json` (or, in a repository of several
|
|
32
32
|
components, the file `sovereign.json` names for it) and `## [X.Y.Z] - date` in its changelog, in plain words for someone upgrading. A
|
|
33
33
|
promotion titled `Release` with that version's tag publishes it on merge (`RELEASING.md`).
|
|
34
|
+
- **The version follows the change, by semver:** a `fix/` is a patch, a `feat/` a minor, a breaking change a major with a note for whoever
|
|
35
|
+
upgrades; `chore/` and `docs/` change no version unless they change what the app offers. Its tag is `vX.Y.Z`, with the `tagPrefix`
|
|
36
|
+
`package.json` names in front, made on the promotion's merge commit, never by hand.
|
|
37
|
+
- **One task, one branch, one pull request,** reviewed before the next begins. `develop` and `main` are never rewritten: fix a commit
|
|
38
|
+
message before it reaches `develop`.
|
|
34
39
|
- **CI runs only for `main`:** on pull requests into it that are not drafts, before a release and by hand; never for `develop` or a
|
|
35
|
-
feature branch, which the pre-push hook (`
|
|
40
|
+
feature branch, which the pre-push hook (`__RUN__ verify`) checks locally.
|
|
36
41
|
- **Verify before claiming done,** and show the output. A regression test is trusted only after it has been seen to fail against the code
|
|
37
42
|
it guards.
|
|
38
43
|
- **Docs are part of the change:** a statement a change makes false is fixed in the same change.
|
|
39
|
-
- **Flag Docker-config impact immediately:** a new or renamed environment variable, port, on-disk path or native dependency
|
|
40
|
-
`Dockerfile`, `.dockerignore`
|
|
44
|
+
- **Flag Docker-config impact immediately:** a new or renamed environment variable, port, on-disk path or native dependency may need the
|
|
45
|
+
`Dockerfile`, `.dockerignore` or `compose.yml` changed. Those are shared files, the same in every app: change them in the template, or
|
|
46
|
+
list the one this app must keep as its own under `sovereign.unmanaged` and change it here, in the same change.
|
|
41
47
|
- **Shared files are written, not edited:** the files `npm create @sovereignfs app sync` writes (this section among them) are changed
|
|
42
48
|
in the template, in sovereignfs/sovereign, and taken with the next sync; a file this app keeps as its own is listed in `package.json`
|
|
43
49
|
under `sovereign.unmanaged`.
|
|
50
|
+
- **Commands are this app's package manager's:** `__INSTALL__`, `__RUN__ dev`, `__RUN__ build`, `__RUN__ verify`. Never add a second
|
|
51
|
+
lockfile.
|
|
52
|
+
|
|
53
|
+
## Rules every app of the suite keeps
|
|
54
|
+
|
|
55
|
+
- **Naming:** user-facing text says "app"; "client" is the protocol term, for code and the settings that register one. Every environment
|
|
56
|
+
variable carries the app's prefix (`__PREFIX___`), and every one the code reads is declared in `.env.example`, a secret also as
|
|
57
|
+
`NAME_FILE`.
|
|
58
|
+
- **No secret has a default:** a required setting the app cannot start without stops it at start-up, saying which; it is never filled in.
|
|
59
|
+
- **Every server action and route decides for itself:** it asks who is calling (the session) before it reads or changes anything, and
|
|
60
|
+
one that changes something checks the request came from the app's own origin. A page's guard protects nothing, since a `'use server'`
|
|
61
|
+
function is a public endpoint.
|
|
62
|
+
- **A person's data is theirs alone:** every statement that reads, changes or deletes it names the owner, from the session, never from
|
|
63
|
+
the request; their data and files are deleted with the notice that they deleted their account.
|
|
64
|
+
- **People's files go only through `@sovereignfs/storage`,** in the app's own folder; a type is judged by the bytes, and only an image is
|
|
65
|
+
shown inline.
|
|
66
|
+
- **Tokens and keys are compared in constant time,** never logged, and the refresh token is the SDK's to send; nothing from a request is
|
|
67
|
+
put into a shell command.
|
|
68
|
+
- **Every outbound `fetch` has a timeout,** and a server render never waits on another service without one.
|
|
69
|
+
- **The data layer is async and migrations only move forward:** a migration in `migrations/` is applied once, in name order, at start;
|
|
70
|
+
one that has been released is never edited, and a change is a new file.
|
|
71
|
+
- **Configuration is read at run time:** never `NEXT_PUBLIC_*` for a value that differs between instances, since it is fixed at build;
|
|
72
|
+
the image bakes in no environment and no `.env` file.
|
|
73
|
+
- **The interface is `@sovereignfs/ui`'s:** its components, and its semantic `--sv-*` tokens for colour; no hard-coded colour, no
|
|
74
|
+
Tailwind, no CSS-in-JS. The content security policy is a nonce, never `'unsafe-inline'` for scripts.
|
|
75
|
+
- **Read the Next.js docs that come with the installed version** (`node_modules/next/dist/docs/`) before writing Next.js code; it
|
|
76
|
+
changes faster than anything remembered.
|
|
44
77
|
|
|
45
78
|
<!-- sovereign:shared:end -->
|
|
46
79
|
|
|
@@ -47,8 +47,8 @@ CI runs only where a change is about to reach what is released:
|
|
|
47
47
|
- by hand, for any branch: **Actions → CI → Run workflow**.
|
|
48
48
|
|
|
49
49
|
It never runs on a push to `develop` or a feature branch, nor on a pull request into `develop`, so runner time is not spent on every
|
|
50
|
-
commit. Those are checked on your machine instead: where the repository has versioned hooks in `.githooks/` (an app's `
|
|
51
|
-
them on), the pre-push hook runs its checks (`
|
|
50
|
+
commit. Those are checked on your machine instead: where the repository has versioned hooks in `.githooks/` (an app's `__INSTALL__` turns
|
|
51
|
+
them on), the pre-push hook runs its checks (`__RUN__ verify`) before anything is pushed. This is the CI strategy of every repository of
|
|
52
52
|
the suite.
|
|
53
53
|
|
|
54
54
|
## Promoting `develop` into `main`
|
|
@@ -69,7 +69,7 @@ work either way.
|
|
|
69
69
|
## Shared files
|
|
70
70
|
|
|
71
71
|
Some files are the same in every app of the suite and are written, not edited: `.github/workflows/promotion.yml`, `release.yml` and
|
|
72
|
-
`sync-develop.yml`, `.github/repository.json`, `CLAUDE.md`, and the shared sections of this file, `RELEASING.md` and `AGENTS.md`. They come
|
|
72
|
+
`sync-develop.yml`, `.github/repository.json`, `CLAUDE.md`, the `Dockerfile`, `.dockerignore` and `compose.yml`, and the shared sections of this file, `RELEASING.md` and `AGENTS.md`. They come
|
|
73
73
|
from the template of the version of `@sovereignfs/create` that `package.json` pins:
|
|
74
74
|
|
|
75
75
|
```bash
|
package/template/app/Dockerfile
CHANGED
|
@@ -4,23 +4,24 @@
|
|
|
4
4
|
# The manifest (sovereign.manifest.json) is the one place the port is written, and the image's label is made from it, so build with the
|
|
5
5
|
# arguments @sovereignfs/manifest prints from it:
|
|
6
6
|
#
|
|
7
|
-
# eval "docker build $(
|
|
7
|
+
# eval "docker build $(__EXEC__ sovereign-manifest docker-args) -t __NAME__ ."
|
|
8
8
|
|
|
9
9
|
ARG NODE_VERSION=24
|
|
10
10
|
|
|
11
11
|
FROM node:${NODE_VERSION}-alpine AS build
|
|
12
12
|
WORKDIR /app
|
|
13
|
-
|
|
14
|
-
|
|
13
|
+
# __COREPACK__
|
|
14
|
+
COPY __INSTALL_FILES__ ./
|
|
15
|
+
RUN __CI_INSTALL__
|
|
15
16
|
COPY . .
|
|
16
17
|
ENV NEXT_TELEMETRY_DISABLED=1
|
|
17
|
-
RUN
|
|
18
|
+
RUN __RUN__ build
|
|
18
19
|
|
|
19
20
|
FROM node:${NODE_VERSION}-alpine AS run
|
|
20
21
|
# The port comes from the manifest, as the build argument sovereign-manifest docker-args gives. A build without it would listen where the
|
|
21
22
|
# instance does not look, so it stops here.
|
|
22
23
|
ARG PORT
|
|
23
|
-
RUN test -n "${PORT}" || { echo 'Build with: eval "docker build $(
|
|
24
|
+
RUN test -n "${PORT}" || { echo 'Build with: eval "docker build $(__EXEC__ sovereign-manifest docker-args) ."' >&2; exit 1; }
|
|
24
25
|
ENV NODE_ENV=production \
|
|
25
26
|
NEXT_TELEMETRY_DISABLED=1 \
|
|
26
27
|
PORT=${PORT} \
|
package/template/app/README.md
CHANGED
|
@@ -1,30 +1,33 @@
|
|
|
1
1
|
# **TITLE**
|
|
2
2
|
|
|
3
3
|
An app for a [Sovereign](https://github.com/sovereignfs/sovereign) instance, made with `npm create @sovereignfs app`. It signs people
|
|
4
|
-
in through the instance's core, keeps its own data in its own PostgreSQL database, and can be hosted by the instance's toolkit as it
|
|
4
|
+
in with accounts of its own, through the instance's core, or both (`@sovereignfs/auth`), keeps its own data in its own PostgreSQL database, and can be hosted by the instance's toolkit as it
|
|
5
5
|
stands. It is a starting point: a notes page, to show the pieces. Change it into your app.
|
|
6
6
|
|
|
7
7
|
## What is here
|
|
8
8
|
|
|
9
|
-
| Where
|
|
10
|
-
|
|
|
11
|
-
| `sovereign.manifest.json`
|
|
12
|
-
| `Dockerfile`
|
|
13
|
-
| `.github/workflows/publish.yml`
|
|
14
|
-
| `CONTRIBUTING.md`
|
|
15
|
-
| `RELEASING.md`, `CHANGELOG.md`
|
|
16
|
-
| `AGENTS.md`, `CLAUDE.md`
|
|
17
|
-
| `.github/repository.json`
|
|
18
|
-
| `.github/workflows/promotion.yml`, `release.yml`
|
|
19
|
-
| `.github/workflows/ci.yml`, `.githooks/pre-push`
|
|
20
|
-
| `.github/workflows/sync-develop.yml`
|
|
21
|
-
| `
|
|
22
|
-
| `
|
|
23
|
-
| `app/api/
|
|
24
|
-
| `
|
|
25
|
-
| `app/
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
9
|
+
| Where | What |
|
|
10
|
+
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| `sovereign.manifest.json` | The manifest, the one copy: what the instance needs to know to host it (its address paths, the scopes it asks for, its port and health path) |
|
|
12
|
+
| `Dockerfile` | One image, not root, on the manifest's port. Its label and port are made from the manifest when it is built |
|
|
13
|
+
| `.github/workflows/publish.yml` | On a `vX.Y.Z` tag of a commit on `main`, builds the image for amd64 and arm64 and publishes it to `ghcr.io/<owner>/<repository>` |
|
|
14
|
+
| `CONTRIBUTING.md` | How work lands on `develop` and is released to `main` (below) |
|
|
15
|
+
| `RELEASING.md`, `CHANGELOG.md` | How a version is released (a promotion titled `Release vX.Y.Z`), and each version's notes |
|
|
16
|
+
| `AGENTS.md`, `CLAUDE.md` | The conventions for agents: the app's own sections, and one shared by every app of the suite |
|
|
17
|
+
| `.github/repository.json` | The repository's merge settings and rulesets, as code (`npm create @sovereignfs app settings apply`) |
|
|
18
|
+
| `.github/workflows/promotion.yml`, `release.yml` | The promotion check and the release on merge, which call the workflows every app shares |
|
|
19
|
+
| `.github/workflows/ci.yml`, `.githooks/pre-push` | The checks: CI for pull requests into `main` and release tags only, the pre-push hook for everything else |
|
|
20
|
+
| `.github/workflows/sync-develop.yml` | After a promotion into `main` is merged, fast-forwards `develop` to the merge commit |
|
|
21
|
+
| `lib/sign-in.ts`, `lib/session.ts` | The sign-in ([`@sovereignfs/auth`](https://www.npmjs.com/package/@sovereignfs/auth)): its ways in, from the settings, and the session |
|
|
22
|
+
| `app/sign-in/`, `app/sign-up/`, `app/security/` | The sign-in and sign-up pages, and a person's password and sessions |
|
|
23
|
+
| `app/api/auth/`, `app/api/sovereign/` | The sign-in's routes, core's back-channel logout, and core's notice that a person deleted their account (`lib/notices.ts`) |
|
|
24
|
+
| `lib/sovereign.ts`, `lib/stores.ts` | Core as a way in: the SDK, and where it keeps refresh tokens (your database; encrypted) |
|
|
25
|
+
| `app/api/health/route.ts` | Answers 200 when the database does |
|
|
26
|
+
| `instrumentation.ts`, `lib/migrate.ts`, `migrations/` | The app applies its own migrations when it starts, each once |
|
|
27
|
+
| `app/page.tsx` | A page behind sign-in, using [`@sovereignfs/ui`](https://www.npmjs.com/package/@sovereignfs/ui) |
|
|
28
|
+
| `lib/files.ts`, `app/api/files/`, `app/upload.tsx` | People's files, kept the suite's way: a folder and a quota for each person, served only to them (below) |
|
|
29
|
+
| `lib/push.ts`, `app/api/push/`, `app/notifications.tsx` | Notifications on a person's devices (Web Push), from a key the instance makes (below) |
|
|
30
|
+
| `compose.yml` | Runs the app and a PostgreSQL database for it on your own machine with Docker (below) |
|
|
28
31
|
|
|
29
32
|
## Branches and releases
|
|
30
33
|
|
|
@@ -39,8 +42,8 @@ The image's label (which is how an instance reads the manifest without pulling t
|
|
|
39
42
|
`sovereign.manifest.json` by [`@sovereignfs/manifest`](https://www.npmjs.com/package/@sovereignfs/manifest), so build with what it prints:
|
|
40
43
|
|
|
41
44
|
```bash
|
|
42
|
-
|
|
43
|
-
eval "docker build $(
|
|
45
|
+
__INSTALL__
|
|
46
|
+
eval "docker build $(__EXEC__ sovereign-manifest docker-args) -t ghcr.io/you/__NAME__:0.1.0 ."
|
|
44
47
|
docker push ghcr.io/you/__NAME__:0.1.0
|
|
45
48
|
```
|
|
46
49
|
|
|
@@ -58,7 +61,7 @@ then, in your instance repository:
|
|
|
58
61
|
```
|
|
59
62
|
|
|
60
63
|
`sv` reads the manifest from the image's label, shows you the scopes it asks for, gives it its address, its port (as `PORT`), its database and
|
|
61
|
-
its secrets, and registers it with core. Change `sovereign.manifest.json` and build again; `
|
|
64
|
+
its secrets, and registers it with core. Change `sovereign.manifest.json` and build again; `__RUN__ manifest:check` says whether it is
|
|
62
65
|
valid.
|
|
63
66
|
|
|
64
67
|
## People's files
|
|
@@ -66,7 +69,7 @@ valid.
|
|
|
66
69
|
The manifest says `"storage": true`, so an instance gives the app a folder of its own for the files people upload, at `/data/s3/__NAME__`,
|
|
67
70
|
and nothing else of its disk ([`app-manifest.md`](https://github.com/sovereignfs/sovereign/blob/main/contracts/app-manifest.md) §2.7).
|
|
68
71
|
`lib/files.ts` makes the store with [`@sovereignfs/storage`](https://www.npmjs.com/package/@sovereignfs/storage): one folder for each
|
|
69
|
-
person, named by `session.
|
|
72
|
+
person, named by the person's id here (`session.user.id`), and a quota for each person (`__PREFIX___STORAGE_QUOTA_MB` and `__PREFIX___STORAGE_FILE_QUOTA`, which an
|
|
70
73
|
operator can change; 200 GB and 1000 files unless they do).
|
|
71
74
|
|
|
72
75
|
- `POST /api/files` keeps a file (the body is the file, its name is in `X-File-Name`), `GET /api/files` lists the person's own,
|
|
@@ -75,10 +78,28 @@ operator can change; 200 GB and 1000 files unless they do).
|
|
|
75
78
|
- A file is served whole or by `Range`, so a video can be sought in and a download resumed.
|
|
76
79
|
- Images are shown, and everything else is downloaded: what a file is comes from its bytes, so nothing uploaded runs as script.
|
|
77
80
|
- A refusal is a `StorageError` with a code and words a person can act on (`over_quota`, `too_large`), which the routes pass on.
|
|
78
|
-
- When a person deletes their account, `onAccountDeleted` in `lib/
|
|
81
|
+
- When a person deletes their account, `onAccountDeleted` in `lib/notices.ts` deletes their folder along with their notes.
|
|
79
82
|
|
|
80
83
|
If your app keeps no files, set `"storage": false` (or remove it), delete `lib/files.ts`, `app/api/files/` and `app/upload.tsx`, and the
|
|
81
|
-
`files()` calls in `lib/
|
|
84
|
+
`files()` calls in `lib/notices.ts`, `app/actions.ts` and `app/page.tsx`.
|
|
85
|
+
|
|
86
|
+
## Notifications
|
|
87
|
+
|
|
88
|
+
The manifest asks the instance for `__PREFIX___VAPID_PRIVATE_KEY` (`generate`), so a hosted app can notify people on a phone or a computer
|
|
89
|
+
where it is not open, with [`@sovereignfs/push`](https://www.npmjs.com/package/@sovereignfs/push). Running it yourself, make a key with
|
|
90
|
+
`npx @sovereignfs/push keys`; without one the app sends no notifications and the home page says nothing of them. Away from an https
|
|
91
|
+
address, set `__PREFIX___VAPID_SUBJECT` to a `mailto:` address.
|
|
92
|
+
|
|
93
|
+
- A person turns them on for a device with the switch on the home page (`app/notifications.tsx`), which sends the device's subscription
|
|
94
|
+
to `app/api/push/subscription`; "Send me a test notification" shows the whole path.
|
|
95
|
+
- `lib/push.ts` keeps devices and waiting pushes in your database (`migrations/002_push.sql`), a device's keys sealed. To notify someone,
|
|
96
|
+
call `enqueuePush(pushStore(client), { account, message, now: Date.now() })` with the client of the transaction that makes the change,
|
|
97
|
+
as `app/push-actions.ts` does: a change rolled back sends nothing. The outbox, started in `instrumentation.ts`, sends what is waiting.
|
|
98
|
+
- Signing out turns the device off first, and a deleted account's devices are forgotten (`lib/notices.ts`).
|
|
99
|
+
|
|
100
|
+
If your app sends no notifications, remove the key from `generate`, and delete `lib/push.ts`, `app/api/push/`, `app/notifications.tsx`,
|
|
101
|
+
`app/push-actions.ts` and their calls in `app/page.tsx`, `app/sw.js/route.ts`, `app/sign-out.tsx`, `instrumentation.ts` and
|
|
102
|
+
`lib/notices.ts`.
|
|
82
103
|
|
|
83
104
|
## Run it with Docker
|
|
84
105
|
|
|
@@ -86,25 +107,36 @@ If your app keeps no files, set `"storage": false` (or remove it), delete `lib/f
|
|
|
86
107
|
so the code is the same in both:
|
|
87
108
|
|
|
88
109
|
```bash
|
|
89
|
-
cp .env.example .env # and
|
|
110
|
+
cp .env.example .env # and, to sign in through an instance too, a core you can reach and its client there
|
|
90
111
|
docker compose up --build # http://localhost:__PORT__
|
|
91
112
|
```
|
|
92
113
|
|
|
93
114
|
The image makes `/data/s3/__NAME__` and gives it to the user the app runs as, which is what lets Docker's volume be written by it.
|
|
94
115
|
|
|
95
|
-
Two things to know. A person is identified by `session.
|
|
96
|
-
`onAccountDeleted` in `lib/
|
|
116
|
+
Two things to know. A person is identified by `session.user.id` and by nothing else, however they signed in. And when you add data about
|
|
117
|
+
people, delete it in `onAccountDeleted` in `lib/notices.ts`, which core calls when someone who came through it deletes their account.
|
|
97
118
|
|
|
98
119
|
## Run it on your machine
|
|
99
120
|
|
|
100
121
|
```bash
|
|
101
|
-
cp .env.example .env # point it at a core you can reach
|
|
102
|
-
|
|
122
|
+
cp .env.example .env # point it at a PostgreSQL database, and at a core you can reach to sign in through one
|
|
123
|
+
__RUN__ dev # http://localhost:__PORT__
|
|
103
124
|
```
|
|
104
125
|
|
|
105
|
-
The port is `port` in `sovereign.manifest.json`, the one copy: the image listens on it, and `
|
|
126
|
+
The port is `port` in `sovereign.manifest.json`, the one copy: the image listens on it, and `__RUN__ dev`, `__RUN__ start` and
|
|
106
127
|
`__PREFIX___URL` in `.env.example` were made with it. To change it, change the manifest, the `dev` and `start` scripts and
|
|
107
128
|
`__PREFIX___URL` together.
|
|
108
129
|
|
|
130
|
+
## How people sign in
|
|
131
|
+
|
|
132
|
+
`__PREFIX___AUTH_LOCAL` turns on accounts of the app's own: a password the browser derives before it is sent, so the app never receives
|
|
133
|
+
the one a person types, and their sessions. `__PREFIX___CORE_URL` turns on core as a way in, "Continue with Sovereign"; with core the only
|
|
134
|
+
way in, the sign-in page sends a person straight on to it. Without a core address the app's own accounts are on; with one they are off unless
|
|
135
|
+
`__PREFIX___AUTH_LOCAL=true`. `__PREFIX___AUTH_SIGNUP` says who may make an account: `open`, or `closed` (the first account only). An
|
|
136
|
+
instance hosting the app gives it a core address, so there it signs people in through core. Signing out of an app an instance hosts
|
|
137
|
+
signs out of core too.
|
|
138
|
+
|
|
139
|
+
An app made with `--encryption` signs in through core with the SDK's `nextAuth` instead (`ENCRYPTION.md`).
|
|
140
|
+
|
|
109
141
|
See [Using the SDK](https://github.com/sovereignfs/sovereign/blob/main/docs/using-the-sdk.md) for what `sv.as(person)` can call, and
|
|
110
142
|
[the app manifest](https://github.com/sovereignfs/sovereign/blob/main/contracts/app-manifest.md) for what the instance gives and expects.
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# What the instance gives this app (contracts/app-manifest.md §3), for running it on your own machine against a core you can reach.
|
|
2
2
|
# A secret may be given as NAME_FILE=/path instead of NAME=value.
|
|
3
3
|
__PREFIX___URL=http://localhost:__PORT__
|
|
4
|
-
|
|
4
|
+
# Core, to sign people in through an instance too: its address and this app's client there. Leave them empty for no core.
|
|
5
|
+
__PREFIX___CORE_URL=
|
|
5
6
|
__PREFIX___CORE_CLIENT_ID=
|
|
6
7
|
__PREFIX___CORE_CLIENT_SECRET=
|
|
7
8
|
__PREFIX___DB_DIALECT=postgres
|
|
@@ -12,6 +13,10 @@ __PREFIX___POSTGRES_DIRECT_URL=postgres://user:password@localhost:5432/__NAME__
|
|
|
12
13
|
# database role to that number plus 2. Without it, 10.
|
|
13
14
|
__PREFIX___POSTGRES_POOL_MAX=10
|
|
14
15
|
__PREFIX___AUTH_SECRET=change-me-to-something-long-and-random
|
|
16
|
+
# How people sign in (@sovereignfs/auth): accounts of the app's own (true or false; on by default when there is no core), and who may
|
|
17
|
+
# make one (open, or closed: the first account only). With CORE_URL set, people can also sign in through core.
|
|
18
|
+
__PREFIX___AUTH_LOCAL=true
|
|
19
|
+
__PREFIX___AUTH_SIGNUP=closed
|
|
15
20
|
# People's files (contracts/app-manifest.md §2.7). An instance mounts this app's folder at /data/s3/__NAME__ and sets these; running it yourself,
|
|
16
21
|
# the folder is here (docker compose mounts a volume at /data/s3/__NAME__ instead). Each person's quota: megabytes and files.
|
|
17
22
|
__PREFIX___STORAGE_DRIVER=fs
|
|
@@ -20,3 +25,8 @@ __PREFIX___STORAGE_QUOTA_MB=204800
|
|
|
20
25
|
__PREFIX___STORAGE_FILE_QUOTA=1000
|
|
21
26
|
# Signs the addresses that serve a file without a session, for a few minutes. At least 32 characters. An instance makes its own.
|
|
22
27
|
__PREFIX___STORAGE_SIGNING_KEY=change-me-to-something-at-least-thirty-two-characters
|
|
28
|
+
# Notifications (Web Push, @sovereignfs/push): the app's key, 32 bytes in URL-safe base64. An instance makes its own; running it yourself,
|
|
29
|
+
# make one with `npx @sovereignfs/push keys`. Empty: the app sends no notifications.
|
|
30
|
+
__PREFIX___VAPID_PRIVATE_KEY=
|
|
31
|
+
# Whom the browsers' push services may contact about this app: mailto: or https:, never localhost. Empty: __PREFIX___URL, when that is https.
|
|
32
|
+
__PREFIX___VAPID_SUBJECT=
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
#!/bin/sh
|
|
2
2
|
# Checks the work before it is pushed (CONTRIBUTING.md, "Continuous integration"): CI does not run for `develop` or a feature branch,
|
|
3
|
-
# so this is their check. `
|
|
3
|
+
# so this is their check. `__INSTALL__` turns it on (a script in package.json sets core.hooksPath to .githooks). Skip it once, knowingly,
|
|
4
4
|
# with `git push --no-verify`.
|
|
5
|
-
exec
|
|
5
|
+
exec __RUN__ verify
|
|
@@ -41,7 +41,8 @@ jobs:
|
|
|
41
41
|
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
42
42
|
with:
|
|
43
43
|
node-version: 24
|
|
44
|
-
|
|
45
|
-
- run:
|
|
46
|
-
- run:
|
|
47
|
-
- run:
|
|
44
|
+
# __COREPACK_STEP__
|
|
45
|
+
- run: __CI_INSTALL__
|
|
46
|
+
- run: __RUN__ typecheck
|
|
47
|
+
- run: __RUN__ manifest:check
|
|
48
|
+
- run: __RUN__ build
|
|
@@ -61,7 +61,8 @@ jobs:
|
|
|
61
61
|
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
62
62
|
with:
|
|
63
63
|
node-version: 24
|
|
64
|
-
|
|
64
|
+
# __COREPACK_STEP__
|
|
65
|
+
- run: __CI_INSTALL__
|
|
65
66
|
|
|
66
67
|
# The tag names the version, so it has to be the one the package says. The image is tagged X.Y.Z, without the v.
|
|
67
68
|
- id: version
|
|
@@ -77,15 +78,15 @@ jobs:
|
|
|
77
78
|
echo "version=$expected" >> "$GITHUB_OUTPUT"
|
|
78
79
|
|
|
79
80
|
# The release notes are the version's CHANGELOG.md section (RELEASING.md); a version without one is not published.
|
|
80
|
-
- run:
|
|
81
|
+
- run: __EXEC__ create app release notes "$TAG" > /dev/null
|
|
81
82
|
env:
|
|
82
83
|
TAG: ${{ inputs.tag || github.ref_name }}
|
|
83
84
|
|
|
84
85
|
# Fails the build on a manifest an instance would refuse.
|
|
85
|
-
- run:
|
|
86
|
+
- run: __EXEC__ sovereign-manifest check
|
|
86
87
|
|
|
87
88
|
- id: manifest
|
|
88
|
-
run:
|
|
89
|
+
run: __EXEC__ sovereign-manifest docker-args --format github >> "$GITHUB_OUTPUT"
|
|
89
90
|
|
|
90
91
|
- id: image
|
|
91
92
|
run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
|
|
@@ -120,12 +121,13 @@ jobs:
|
|
|
120
121
|
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
121
122
|
with:
|
|
122
123
|
node-version: 24
|
|
123
|
-
|
|
124
|
+
# __COREPACK_STEP__
|
|
125
|
+
- run: __CI_INSTALL__
|
|
124
126
|
- env:
|
|
125
127
|
GH_TOKEN: ${{ github.token }}
|
|
126
128
|
TAG: ${{ inputs.tag || github.ref_name }}
|
|
127
129
|
run: |
|
|
128
|
-
|
|
130
|
+
__EXEC__ create app release notes "$TAG" > notes.md
|
|
129
131
|
if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
|
|
130
132
|
gh release edit "$TAG" --repo "$GITHUB_REPOSITORY" --notes-file notes.md
|
|
131
133
|
else
|
package/template/app/_gitignore
CHANGED
|
@@ -1,36 +1,62 @@
|
|
|
1
1
|
'use server';
|
|
2
2
|
|
|
3
3
|
import { revalidatePath } from 'next/cache';
|
|
4
|
-
import {
|
|
4
|
+
import { headers } from 'next/headers';
|
|
5
|
+
import { redirect } from 'next/navigation';
|
|
6
|
+
import { coreSignOutUrl } from '@sovereignfs/auth/core';
|
|
7
|
+
import { getSession } from '@/lib/session';
|
|
8
|
+
import { signIn, waysIn } from '@/lib/sign-in';
|
|
9
|
+
import { sovereign } from '@/lib/sovereign';
|
|
5
10
|
import { db } from '@/lib/db';
|
|
6
11
|
import { files } from '@/lib/files';
|
|
7
12
|
import { StorageError } from '@sovereignfs/storage';
|
|
8
13
|
|
|
9
|
-
/**
|
|
14
|
+
/** The signed-in person, or the sign-in page: every server action is a public POST endpoint, so each one asks who is calling first. */
|
|
15
|
+
async function signedIn() {
|
|
16
|
+
const session = await getSession();
|
|
17
|
+
if (!session) redirect('/sign-in');
|
|
18
|
+
return session;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Signs out. A session that came from core goes on through core's sign-out, which decides whether it ends core's session too
|
|
23
|
+
* (core-app §3.6.5); the address is read before the session ends, since it goes with it.
|
|
24
|
+
*/
|
|
25
|
+
export async function signOut(): Promise<void> {
|
|
26
|
+
const session = await getSession();
|
|
27
|
+
const { auth, database } = await signIn();
|
|
28
|
+
const throughCore =
|
|
29
|
+
session && waysIn().core
|
|
30
|
+
? await coreSignOutUrl(database, sovereign(), session.session.id)
|
|
31
|
+
: undefined;
|
|
32
|
+
await auth.api.signOut({ headers: await headers() });
|
|
33
|
+
redirect(throughCore ?? '/sign-in');
|
|
34
|
+
}
|
|
35
|
+
|
|
10
36
|
export async function addNote(formData: FormData): Promise<void> {
|
|
11
|
-
const session = await
|
|
37
|
+
const session = await signedIn();
|
|
12
38
|
const body = String(formData.get('body') ?? '')
|
|
13
39
|
.trim()
|
|
14
40
|
.slice(0, 2000);
|
|
15
41
|
if (body === '') return;
|
|
16
|
-
await db().query('INSERT INTO notes (owner, body) VALUES ($1, $2)', [session.
|
|
42
|
+
await db().query('INSERT INTO notes (owner, body) VALUES ($1, $2)', [session.user.id, body]);
|
|
17
43
|
revalidatePath('/');
|
|
18
44
|
}
|
|
19
45
|
|
|
20
46
|
export async function deleteNote(formData: FormData): Promise<void> {
|
|
21
|
-
const session = await
|
|
47
|
+
const session = await signedIn();
|
|
22
48
|
const id = Number(formData.get('id'));
|
|
23
49
|
if (!Number.isSafeInteger(id)) return;
|
|
24
50
|
// Only the person's own: the owner is part of the condition and not a check made before it.
|
|
25
|
-
await db().query('DELETE FROM notes WHERE id = $1 AND owner = $2', [id, session.
|
|
51
|
+
await db().query('DELETE FROM notes WHERE id = $1 AND owner = $2', [id, session.user.id]);
|
|
26
52
|
revalidatePath('/');
|
|
27
53
|
}
|
|
28
54
|
|
|
29
55
|
export async function deleteFile(formData: FormData): Promise<void> {
|
|
30
|
-
const session = await
|
|
56
|
+
const session = await signedIn();
|
|
31
57
|
try {
|
|
32
58
|
// Only the person's own: the store is asked for the person's folder, so another person's file is a file that is not there.
|
|
33
|
-
await files().remove(session.
|
|
59
|
+
await files().remove(session.user.id, String(formData.get('id') ?? ''));
|
|
34
60
|
} catch (error) {
|
|
35
61
|
if (!(error instanceof StorageError && error.code === 'not_found')) throw error;
|
|
36
62
|
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// The sign-in's routes (better-auth on `@sovereignfs/auth`), and signing in through core: /api/auth/sign-in/sovereign and
|
|
2
|
+
// /api/auth/callback/sovereign, the address in sovereign.manifest.json.
|
|
3
|
+
import { signIn } from '@/lib/sign-in';
|
|
4
|
+
|
|
5
|
+
export const dynamic = 'force-dynamic';
|
|
6
|
+
|
|
7
|
+
const handle = async (request: Request) => (await signIn()).auth.handler(request);
|
|
8
|
+
|
|
9
|
+
export const GET = handle;
|
|
10
|
+
export const POST = handle;
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { getSession } from '@/lib/session';
|
|
2
2
|
import { failure, files, refuseCrossOrigin, unauthorised } from '@/lib/files';
|
|
3
3
|
|
|
4
4
|
export const dynamic = 'force-dynamic';
|
|
@@ -9,9 +9,7 @@ type Context = { params: Promise<{ id: string }> };
|
|
|
9
9
|
export async function GET(request: Request, { params }: Context) {
|
|
10
10
|
const { id } = await params;
|
|
11
11
|
const query = new URL(request.url).searchParams;
|
|
12
|
-
const sub = query.has('signature')
|
|
13
|
-
? files().signedFor(id, query)
|
|
14
|
-
: (await auth().getSession())?.sub;
|
|
12
|
+
const sub = query.has('signature') ? files().signedFor(id, query) : (await getSession())?.user.id;
|
|
15
13
|
if (!sub) return query.has('signature') ? expired() : unauthorised();
|
|
16
14
|
try {
|
|
17
15
|
return await files().serve(sub, id, request);
|
|
@@ -26,10 +24,10 @@ export async function GET(request: Request, { params }: Context) {
|
|
|
26
24
|
export async function DELETE(request: Request, { params }: Context) {
|
|
27
25
|
const refused = refuseCrossOrigin(request);
|
|
28
26
|
if (refused) return refused;
|
|
29
|
-
const session = await
|
|
27
|
+
const session = await getSession();
|
|
30
28
|
if (!session) return unauthorised();
|
|
31
29
|
try {
|
|
32
|
-
await files().remove(session.
|
|
30
|
+
await files().remove(session.user.id, (await params).id);
|
|
33
31
|
return new Response(null, { status: 204 });
|
|
34
32
|
} catch (error) {
|
|
35
33
|
const known = failure(error);
|
|
@@ -1,13 +1,16 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { getSession } from '@/lib/session';
|
|
2
2
|
import { failure, files, refuseCrossOrigin, unauthorised } from '@/lib/files';
|
|
3
3
|
|
|
4
4
|
export const dynamic = 'force-dynamic';
|
|
5
5
|
|
|
6
6
|
/** The signed-in person's own files, newest first, and how much of their space they use. */
|
|
7
7
|
export async function GET() {
|
|
8
|
-
const session = await
|
|
8
|
+
const session = await getSession();
|
|
9
9
|
if (!session) return unauthorised();
|
|
10
|
-
const [list, usage] = await Promise.all([
|
|
10
|
+
const [list, usage] = await Promise.all([
|
|
11
|
+
files().list(session.user.id),
|
|
12
|
+
files().usage(session.user.id),
|
|
13
|
+
]);
|
|
11
14
|
return Response.json(
|
|
12
15
|
{ files: list.map((file) => ({ ...file, url: `/api/files/${file.id}` })), usage },
|
|
13
16
|
{ headers: { 'cache-control': 'no-store' } },
|
|
@@ -18,7 +21,7 @@ export async function GET() {
|
|
|
18
21
|
export async function POST(request: Request) {
|
|
19
22
|
const refused = refuseCrossOrigin(request);
|
|
20
23
|
if (refused) return refused;
|
|
21
|
-
const session = await
|
|
24
|
+
const session = await getSession();
|
|
22
25
|
if (!session) return unauthorised();
|
|
23
26
|
try {
|
|
24
27
|
const length = Number(request.headers.get('content-length') ?? Number.NaN);
|
|
@@ -29,7 +32,7 @@ export async function POST(request: Request) {
|
|
|
29
32
|
name = undefined;
|
|
30
33
|
}
|
|
31
34
|
const record = await files().put(
|
|
32
|
-
session.
|
|
35
|
+
session.user.id,
|
|
33
36
|
(request.body ?? new Uint8Array(0)) as unknown as AsyncIterable<Uint8Array>,
|
|
34
37
|
// Without a length the upload reserves all the room the person has left, so uploads of unknown size run one at a time.
|
|
35
38
|
{ name, ...(Number.isSafeInteger(length) && length >= 0 ? { size: length } : {}) },
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// The route a device turns notifications on and off with (@sovereignfs/push): the signed-in account's devices only, from this app's
|
|
2
|
+
// own pages only (the Origin check), and nothing of it cached.
|
|
3
|
+
import { pushSubscriptionHandlers } from '@sovereignfs/push';
|
|
4
|
+
import { currentAccount } from '@/lib/account';
|
|
5
|
+
import { setting } from '@/lib/config';
|
|
6
|
+
import { originOf } from '@/lib/csp';
|
|
7
|
+
import { appPush, pushStore } from '@/lib/push';
|
|
8
|
+
|
|
9
|
+
export const dynamic = 'force-dynamic';
|
|
10
|
+
|
|
11
|
+
const handlers = () => {
|
|
12
|
+
const origin = originOf(setting('__PREFIX___URL'));
|
|
13
|
+
return pushSubscriptionHandlers({
|
|
14
|
+
store: pushStore(),
|
|
15
|
+
settings: appPush(),
|
|
16
|
+
account: () => currentAccount(),
|
|
17
|
+
...(origin ? { origin } : {}),
|
|
18
|
+
});
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
export const GET = (request: Request) => handlers().GET(request);
|
|
22
|
+
export const POST = (request: Request) => handlers().POST(request);
|
|
23
|
+
export const DELETE = (request: Request) => handlers().DELETE(request);
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
// The salt a page derives the sign-in value with (auth.md §4, rule 1): the vault id, made once (sdk §9.5). It is no secret.
|
|
2
|
+
import { signIn } from '@/lib/sign-in';
|
|
3
|
+
|
|
4
|
+
export const dynamic = 'force-dynamic';
|
|
5
|
+
|
|
6
|
+
export async function GET() {
|
|
7
|
+
const { vault } = await signIn();
|
|
8
|
+
return Response.json({ vaultId: await vault.vaultId() });
|
|
9
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// Core's notice that a person deleted their account at the instance (core-app §4.5): the address in sovereign.manifest.json.
|
|
2
|
+
import { notices } from '@/lib/notices';
|
|
3
|
+
import { waysIn } from '@/lib/sign-in';
|
|
4
|
+
|
|
5
|
+
export const dynamic = 'force-dynamic';
|
|
6
|
+
|
|
7
|
+
export async function POST(request: Request) {
|
|
8
|
+
if (!waysIn().core) return new Response(null, { status: 404 });
|
|
9
|
+
return (await notices()).accountDeleted(request);
|
|
10
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// Core's logout notice (auth.md §8): the back-channel address in sovereign.manifest.json.
|
|
2
|
+
import { notices } from '@/lib/notices';
|
|
3
|
+
import { waysIn } from '@/lib/sign-in';
|
|
4
|
+
|
|
5
|
+
export const dynamic = 'force-dynamic';
|
|
6
|
+
|
|
7
|
+
export async function POST(request: Request) {
|
|
8
|
+
if (!waysIn().core) return new Response(null, { status: 404 });
|
|
9
|
+
return (await notices()).backChannelLogout(request);
|
|
10
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// Core's request for a person's part of their export (core-app §4.7.2): the address in sovereign.manifest.json.
|
|
2
|
+
import { exportPart } from '@/lib/notices';
|
|
3
|
+
import { waysIn } from '@/lib/sign-in';
|
|
4
|
+
|
|
5
|
+
export const dynamic = 'force-dynamic';
|
|
6
|
+
|
|
7
|
+
export async function POST(request: Request) {
|
|
8
|
+
if (!waysIn().core) return new Response(null, { status: 404 });
|
|
9
|
+
return exportPart(request);
|
|
10
|
+
}
|