@sovereignfs/create 0.6.0 → 0.11.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/dist/create.mjs CHANGED
@@ -7,7 +7,7 @@ import { createInterface } from "readline/promises";
7
7
  // package.json
8
8
  var package_default = {
9
9
  name: "@sovereignfs/create",
10
- version: "0.6.0",
10
+ version: "0.11.0",
11
11
  type: "module",
12
12
  description: "npm create @sovereignfs: makes an instance repository, pinned to the toolkit (sv) of the same version.",
13
13
  license: "AGPL-3.0-or-later",
@@ -91,6 +91,8 @@ var GITIGNORE = `node_modules/
91
91
  age.key
92
92
  .env
93
93
  .env.*
94
+ # Backups taken by sv backup, which are never committed: encrypted in .backups/, plain copies in .backups/unsafe/.
95
+ .backups/
94
96
  `;
95
97
  function readme(name) {
96
98
  return `# ${name}
@@ -266,8 +268,10 @@ var APP_DEPENDENCIES = {
266
268
  // `@sovereignfs/ui` is one bundle that imports these two, which it lists as optional peers: an app has to have them for the bundle to load.
267
269
  "@dnd-kit/core": "^6.3.1",
268
270
  "@dnd-kit/sortable": "^10.0.0",
271
+ "@sovereignfs/config": "^0.1.0",
269
272
  "@sovereignfs/sdk": "^2.0.0",
270
- "@sovereignfs/ui": "^0.92.0",
273
+ "@sovereignfs/storage": "^0.1.0",
274
+ "@sovereignfs/ui": "^0.96.1",
271
275
  next: "^16.4.3",
272
276
  pg: "^8.23.1",
273
277
  react: "^19.3.1",
@@ -275,7 +279,7 @@ var APP_DEPENDENCIES = {
275
279
  };
276
280
  var APP_DEV_DEPENDENCIES = {
277
281
  // Makes the image's label and port from the manifest, and checks the manifest (`sovereign-manifest`).
278
- "@sovereignfs/manifest": "^0.1.0",
282
+ "@sovereignfs/manifest": "^0.2.0",
279
283
  "@types/node": "^24.19.2",
280
284
  "@types/pg": "^8.23.1",
281
285
  "@types/react": "^19.3.0",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sovereignfs/create",
3
- "version": "0.6.0",
3
+ "version": "0.11.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",
@@ -30,6 +30,9 @@ COPY --from=build --chown=node:node /app/.next/standalone ./
30
30
  COPY --from=build --chown=node:node /app/.next/static ./.next/static
31
31
  # The migrations are read from disk when the server starts, and Next does not trace them.
32
32
  COPY --from=build --chown=node:node /app/migrations ./migrations
33
+ # People's files (manifest `storage`): an instance mounts this app's own folder here, and running it yourself mounts a volume (compose.yml). The
34
+ # folder is made in the image and is the user's, because Docker makes a volume from it, owned as it is, and a root-owned one cannot be written.
35
+ RUN mkdir -p /data/s3/__NAME__ && chown -R node:node /data
33
36
  USER node
34
37
  EXPOSE ${PORT}
35
38
  CMD ["node", "server.js"]
@@ -16,6 +16,8 @@ stands. It is a starting point: a notes page, to show the pieces. Change it into
16
16
  | `app/api/health/route.ts` | Answers 200 when the database does |
17
17
  | `instrumentation.ts`, `lib/migrate.ts`, `migrations/` | The app applies its own migrations when it starts, each once |
18
18
  | `app/page.tsx` | A page behind sign-in, using [`@sovereignfs/ui`](https://www.npmjs.com/package/@sovereignfs/ui) |
19
+ | `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) |
20
+ | `compose.yml` | Runs the app and a PostgreSQL database for it on your own machine with Docker (below) |
19
21
 
20
22
  ## Build and host it
21
23
 
@@ -45,6 +47,37 @@ then, in your instance repository:
45
47
  its secrets, and registers it with core. Change `sovereign.manifest.json` and build again; `npm run manifest:check` says whether it is
46
48
  valid.
47
49
 
50
+ ## People's files
51
+
52
+ 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__`,
53
+ and nothing else of its disk ([`app-manifest.md`](https://github.com/sovereignfs/sovereign/blob/main/contracts/app-manifest.md) §2.7).
54
+ `lib/files.ts` makes the store with [`@sovereignfs/storage`](https://www.npmjs.com/package/@sovereignfs/storage): one folder for each
55
+ person, named by `session.sub`, and a quota for each person (`__PREFIX___STORAGE_QUOTA_MB` and `__PREFIX___STORAGE_FILE_QUOTA`, which an
56
+ operator can change; 200 GB and 1000 files unless they do).
57
+
58
+ - `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,
59
+ `GET /api/files/{id}` serves one to its owner, and `DELETE /api/files/{id}` removes it. Each asks who is calling, and a request that
60
+ changes something must come from the app's own pages.
61
+ - A file is served whole or by `Range`, so a video can be sought in and a download resumed.
62
+ - Images are shown, and everything else is downloaded: what a file is comes from its bytes, so nothing uploaded runs as script.
63
+ - A refusal is a `StorageError` with a code and words a person can act on (`over_quota`, `too_large`), which the routes pass on.
64
+ - When a person deletes their account, `onAccountDeleted` in `lib/auth.ts` deletes their folder along with their notes.
65
+
66
+ 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
67
+ `files()` calls in `lib/auth.ts`, `app/actions.ts` and `app/page.tsx`.
68
+
69
+ ## Run it with Docker
70
+
71
+ `compose.yml` starts the app and a PostgreSQL database for it, with the files in a volume mounted where an instance mounts the app's folder,
72
+ so the code is the same in both:
73
+
74
+ ```bash
75
+ cp .env.example .env # and give it a core you can reach, and its client there
76
+ docker compose up --build # http://localhost:__PORT__
77
+ ```
78
+
79
+ 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.
80
+
48
81
  Two things to know. A person is identified by `session.sub` and by nothing else. And when you add data about people, delete it in
49
82
  `onAccountDeleted` in `lib/auth.ts`, which core calls when someone deletes their account.
50
83
 
@@ -5,3 +5,5 @@ node_modules
5
5
  .env.*
6
6
  Dockerfile
7
7
  README.md
8
+ data
9
+ compose.yml
@@ -12,3 +12,11 @@ __PREFIX___POSTGRES_DIRECT_URL=postgres://user:password@localhost:5432/__NAME__
12
12
  # database role to that number plus 2. Without it, 10.
13
13
  __PREFIX___POSTGRES_POOL_MAX=10
14
14
  __PREFIX___AUTH_SECRET=change-me-to-something-long-and-random
15
+ # 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
+ # the folder is here (docker compose mounts a volume at /data/s3/__NAME__ instead). Each person's quota: megabytes and files.
17
+ __PREFIX___STORAGE_DRIVER=fs
18
+ __PREFIX___STORAGE_PATH=./data/s3/__NAME__
19
+ __PREFIX___STORAGE_QUOTA_MB=204800
20
+ __PREFIX___STORAGE_FILE_QUOTA=1000
21
+ # Signs the addresses that serve a file without a session, for a few minutes. At least 32 characters. An instance makes its own.
22
+ __PREFIX___STORAGE_SIGNING_KEY=change-me-to-something-at-least-thirty-two-characters
@@ -5,3 +5,5 @@ node_modules/
5
5
  !.env.example
6
6
  *.tgz
7
7
  .DS_Store
8
+ # People's files, when you run the app on your own machine (see .env.example).
9
+ data/
@@ -3,6 +3,8 @@
3
3
  import { revalidatePath } from 'next/cache';
4
4
  import { auth } from '@/lib/auth';
5
5
  import { db } from '@/lib/db';
6
+ import { files } from '@/lib/files';
7
+ import { StorageError } from '@sovereignfs/storage';
6
8
 
7
9
  /** Every server action is a public POST endpoint, so each one asks who is calling before it does anything. */
8
10
  export async function addNote(formData: FormData): Promise<void> {
@@ -23,3 +25,14 @@ export async function deleteNote(formData: FormData): Promise<void> {
23
25
  await db().query('DELETE FROM notes WHERE id = $1 AND owner = $2', [id, session.sub]);
24
26
  revalidatePath('/');
25
27
  }
28
+
29
+ export async function deleteFile(formData: FormData): Promise<void> {
30
+ const session = await auth().requireSession('/');
31
+ try {
32
+ // 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.sub, String(formData.get('id') ?? ''));
34
+ } catch (error) {
35
+ if (!(error instanceof StorageError && error.code === 'not_found')) throw error;
36
+ }
37
+ revalidatePath('/');
38
+ }
@@ -0,0 +1,45 @@
1
+ import { auth } from '@/lib/auth';
2
+ import { failure, files, refuseCrossOrigin, unauthorised } from '@/lib/files';
3
+
4
+ export const dynamic = 'force-dynamic';
5
+
6
+ type Context = { params: Promise<{ id: string }> };
7
+
8
+ /** One file, to its owner: to their session, or through an address signed for them that has not run out. Someone else's is not found. */
9
+ export async function GET(request: Request, { params }: Context) {
10
+ const { id } = await params;
11
+ const query = new URL(request.url).searchParams;
12
+ const sub = query.has('signature')
13
+ ? files().signedFor(id, query)
14
+ : (await auth().getSession())?.sub;
15
+ if (!sub) return query.has('signature') ? expired() : unauthorised();
16
+ try {
17
+ return await files().serve(sub, id, request);
18
+ } catch (error) {
19
+ const known = failure(error);
20
+ if (known) return known;
21
+ throw error;
22
+ }
23
+ }
24
+
25
+ /** Deletes one of the signed-in person's files and gives its space back. */
26
+ export async function DELETE(request: Request, { params }: Context) {
27
+ const refused = refuseCrossOrigin(request);
28
+ if (refused) return refused;
29
+ const session = await auth().getSession();
30
+ if (!session) return unauthorised();
31
+ try {
32
+ await files().remove(session.sub, (await params).id);
33
+ return new Response(null, { status: 204 });
34
+ } catch (error) {
35
+ const known = failure(error);
36
+ if (known) return known;
37
+ throw error;
38
+ }
39
+ }
40
+
41
+ const expired = () =>
42
+ Response.json(
43
+ { error: 'expired', message: 'This link has run out. Open the file again from the app.' },
44
+ { status: 403 },
45
+ );
@@ -0,0 +1,43 @@
1
+ import { auth } from '@/lib/auth';
2
+ import { failure, files, refuseCrossOrigin, unauthorised } from '@/lib/files';
3
+
4
+ export const dynamic = 'force-dynamic';
5
+
6
+ /** The signed-in person's own files, newest first, and how much of their space they use. */
7
+ export async function GET() {
8
+ const session = await auth().getSession();
9
+ if (!session) return unauthorised();
10
+ const [list, usage] = await Promise.all([files().list(session.sub), files().usage(session.sub)]);
11
+ return Response.json(
12
+ { files: list.map((file) => ({ ...file, url: `/api/files/${file.id}` })), usage },
13
+ { headers: { 'cache-control': 'no-store' } },
14
+ );
15
+ }
16
+
17
+ /** Stores a file for the signed-in person. The body is the file itself and its name is in `X-File-Name`, percent-encoded. */
18
+ export async function POST(request: Request) {
19
+ const refused = refuseCrossOrigin(request);
20
+ if (refused) return refused;
21
+ const session = await auth().getSession();
22
+ if (!session) return unauthorised();
23
+ try {
24
+ const length = Number(request.headers.get('content-length') ?? Number.NaN);
25
+ let name: string | undefined;
26
+ try {
27
+ name = decodeURIComponent(request.headers.get('x-file-name') ?? '');
28
+ } catch {
29
+ name = undefined;
30
+ }
31
+ const record = await files().put(
32
+ session.sub,
33
+ (request.body ?? new Uint8Array(0)) as unknown as AsyncIterable<Uint8Array>,
34
+ // Without a length the upload reserves all the room the person has left, so uploads of unknown size run one at a time.
35
+ { name, ...(Number.isSafeInteger(length) && length >= 0 ? { size: length } : {}) },
36
+ );
37
+ return Response.json({ ...record, url: `/api/files/${record.id}` }, { status: 201 });
38
+ } catch (error) {
39
+ const known = failure(error);
40
+ if (known) return known;
41
+ throw error;
42
+ }
43
+ }
@@ -1,7 +1,21 @@
1
1
  import { auth } from '@/lib/auth';
2
2
  import { db } from '@/lib/db';
3
- import { addNote, deleteNote } from './actions';
3
+ import { files } from '@/lib/files';
4
+ import { addNote, deleteFile, deleteNote } from './actions';
4
5
  import { Button, Card, Input, PageHeader } from './ui';
6
+ import { Upload } from './upload';
7
+
8
+ /** A size as a person reads it: 512 KB, 3.4 MB, 200 GB. */
9
+ function size(bytes: number): string {
10
+ const units = ['bytes', 'KB', 'MB', 'GB', 'TB'];
11
+ let value = bytes;
12
+ let unit = 0;
13
+ while (value >= 1024 && unit < units.length - 1) {
14
+ value /= 1024;
15
+ unit += 1;
16
+ }
17
+ return unit === 0 ? `${value} bytes` : `${value.toFixed(value < 10 ? 1 : 0)} ${units[unit]}`;
18
+ }
5
19
 
6
20
  // The page is for the person signed in, so it is made for each request.
7
21
  export const dynamic = 'force-dynamic';
@@ -13,6 +27,8 @@ export default async function Home() {
13
27
  'SELECT id, body FROM notes WHERE owner = $1 ORDER BY id DESC LIMIT 100',
14
28
  [session.sub],
15
29
  );
30
+ // Their files, kept the suite's way: a folder for this person and a quota for this person (lib/files.ts).
31
+ const [kept, usage] = await Promise.all([files().list(session.sub), files().usage(session.sub)]);
16
32
  const name = typeof session.claims.name === 'string' ? session.claims.name : 'there';
17
33
 
18
34
  return (
@@ -39,6 +55,33 @@ export default async function Home() {
39
55
  </li>
40
56
  ))}
41
57
  </ul>
58
+ <Card>
59
+ <div>
60
+ <h2>Files</h2>
61
+ <p>
62
+ {usage.files} of {usage.quota.files} files, {size(usage.bytes)} of{' '}
63
+ {size(usage.quota.bytes)} used
64
+ </p>
65
+ <Upload />
66
+ </div>
67
+ </Card>
68
+ <ul>
69
+ {kept.map((file) => (
70
+ <li key={file.id}>
71
+ <Card>
72
+ <form action={deleteFile}>
73
+ <a href={`/api/files/${file.id}`} style={{ flex: 1 }}>
74
+ {file.name} ({size(file.size)})
75
+ </a>
76
+ <input type="hidden" name="id" value={file.id} />
77
+ <Button type="submit" variant="ghost" size="sm">
78
+ Delete
79
+ </Button>
80
+ </form>
81
+ </Card>
82
+ </li>
83
+ ))}
84
+ </ul>
42
85
  <form action="/auth/logout" method="post">
43
86
  <Button type="submit" variant="secondary">
44
87
  Sign out
@@ -0,0 +1,54 @@
1
+ 'use client';
2
+
3
+ import { useRouter } from 'next/navigation';
4
+ import { useRef, useState } from 'react';
5
+ import { Button, Input } from './ui';
6
+
7
+ /**
8
+ * Sends the chosen file to /api/files as it is, with its name beside it, and shows what the app answered when it would not keep it
9
+ * (too large, no room left). The page is made again afterwards, so the new file is in the list.
10
+ */
11
+ export function Upload() {
12
+ const router = useRouter();
13
+ const input = useRef<HTMLInputElement>(null);
14
+ const [message, setMessage] = useState('');
15
+ const [busy, setBusy] = useState(false);
16
+
17
+ async function send(file: File) {
18
+ setBusy(true);
19
+ setMessage('');
20
+ try {
21
+ const reply = await fetch('/api/files', {
22
+ method: 'POST',
23
+ headers: { 'x-file-name': encodeURIComponent(file.name) },
24
+ body: file,
25
+ });
26
+ if (!reply.ok) {
27
+ const body = (await reply.json().catch(() => ({}))) as { message?: string };
28
+ setMessage(body.message ?? 'That file could not be kept. Try again.');
29
+ return;
30
+ }
31
+ if (input.current) input.current.value = '';
32
+ router.refresh();
33
+ } finally {
34
+ setBusy(false);
35
+ }
36
+ }
37
+
38
+ return (
39
+ <div>
40
+ <Input
41
+ ref={input}
42
+ type="file"
43
+ aria-label="A file to keep"
44
+ disabled={busy}
45
+ onChange={(event) => {
46
+ const file = event.target.files?.[0];
47
+ if (file) void send(file);
48
+ }}
49
+ />
50
+ {busy ? <Button disabled>Sending…</Button> : null}
51
+ {message ? <p role="alert">{message}</p> : null}
52
+ </div>
53
+ );
54
+ }
@@ -0,0 +1,48 @@
1
+ # Runs this app on your own machine with Docker: the app, and a PostgreSQL database for it.
2
+ #
3
+ # cp .env.example .env # point it at a core you can reach, and give it its client there
4
+ # docker compose up --build
5
+ #
6
+ # The app still signs people in through a core: set __PREFIX___CORE_URL, __PREFIX___CORE_CLIENT_ID and __PREFIX___CORE_CLIENT_SECRET in .env. People's
7
+ # files are kept in the volume `files`, mounted where an instance mounts the app's own folder, so the app's code is the same in both
8
+ # (contracts/app-manifest.md §2.7).
9
+ services:
10
+ app:
11
+ build:
12
+ context: .
13
+ args:
14
+ # The manifest's port, which the image listens on. `npx sovereign-manifest docker-args` prints it, with the image's label.
15
+ PORT: '__PORT__'
16
+ ports:
17
+ - '__PORT__:__PORT__'
18
+ env_file: .env
19
+ environment:
20
+ __PREFIX___POSTGRES_URL: postgres://app:app@db:5432/app
21
+ __PREFIX___POSTGRES_DIRECT_URL: postgres://app:app@db:5432/app
22
+ __PREFIX___STORAGE_DRIVER: fs
23
+ __PREFIX___STORAGE_PATH: /data/s3/__NAME__
24
+ volumes:
25
+ - files:/data/s3/__NAME__
26
+ depends_on:
27
+ db:
28
+ condition: service_healthy
29
+ restart: unless-stopped
30
+
31
+ db:
32
+ image: postgres:18-alpine
33
+ environment:
34
+ POSTGRES_USER: app
35
+ POSTGRES_PASSWORD: app
36
+ POSTGRES_DB: app
37
+ volumes:
38
+ - db:/var/lib/postgresql
39
+ healthcheck:
40
+ test: ['CMD-SHELL', 'pg_isready -U app -d app']
41
+ interval: 5s
42
+ timeout: 5s
43
+ retries: 10
44
+ restart: unless-stopped
45
+
46
+ volumes:
47
+ files:
48
+ db:
@@ -1,5 +1,6 @@
1
1
  import { nextAuth } from '@sovereignfs/sdk/next';
2
2
  import { db } from './db';
3
+ import { files } from './files';
3
4
  import { sovereign } from './sovereign';
4
5
 
5
6
  /**
@@ -10,6 +11,8 @@ export const auth = () =>
10
11
  nextAuth(sovereign(), {
11
12
  onAccountDeleted: async ({ sub }) => {
12
13
  await db().query('DELETE FROM notes WHERE owner = $1', [sub]);
14
+ // And the files they uploaded: their folder, which is gone once this has run, however often it does.
15
+ await files().removeAll(sub);
13
16
  // The SDK has already ended the person's sessions and forgotten their refresh token.
14
17
  },
15
18
  });
@@ -0,0 +1,46 @@
1
+ import { defineConfig } from '@sovereignfs/config';
2
+ import {
3
+ createFileStore,
4
+ StorageError,
5
+ storageVariables,
6
+ type FileStore,
7
+ } from '@sovereignfs/storage';
8
+ import { required } from './config';
9
+
10
+ /**
11
+ * The files people upload to this app (contracts/app-manifest.md §2.7): a folder per person and a quota per person, kept by
12
+ * `@sovereignfs/storage`. An instance mounts this app's own folder at /data/s3/__NAME__ and sets the variables; running it yourself, set
13
+ * __PREFIX___STORAGE_PATH (see .env.example). Made when first used, so building the app needs none of it.
14
+ */
15
+ const config = defineConfig({ prefix: '__PREFIX__', variables: { ...storageVariables } });
16
+ let store: FileStore | undefined;
17
+
18
+ export function files(): FileStore {
19
+ store ??= createFileStore(config.load(), {
20
+ prefix: '__PREFIX__',
21
+ defaultPath: '/data/s3/__NAME__',
22
+ });
23
+ return store;
24
+ }
25
+
26
+ /**
27
+ * A route that changes something answers only a request that came from this app's own pages: the cookie is sent with a request from
28
+ * anywhere, so without this a page on another site could make the signed-in person upload or delete.
29
+ */
30
+ export function refuseCrossOrigin(request: Request): Response | undefined {
31
+ const origin = request.headers.get('origin');
32
+ if (origin !== null && origin === new URL(required('__PREFIX___URL')).origin) return undefined;
33
+ return Response.json(
34
+ { error: 'forbidden', message: 'This request did not come from this app.' },
35
+ { status: 403 },
36
+ );
37
+ }
38
+
39
+ /** What a store's refusal looks like to a page: a code, and words a person can act on. Anything else is not caught here. */
40
+ export function failure(error: unknown): Response | undefined {
41
+ if (!(error instanceof StorageError)) return undefined;
42
+ return Response.json({ error: error.code, message: error.message }, { status: error.status });
43
+ }
44
+
45
+ export const unauthorised = () =>
46
+ Response.json({ error: 'unauthorised', message: 'Sign in first.' }, { status: 401 });
@@ -1,5 +1,5 @@
1
1
  {
2
- "manifest": 2,
2
+ "manifest": 3,
3
3
  "prefix": "__PREFIX_LOWER__",
4
4
  "name": "__TITLE__",
5
5
  "description": "Notes, as a starting point for an app on a Sovereign instance",
@@ -14,6 +14,7 @@
14
14
  "scopes": ["openid", "profile", "email", "offline_access"]
15
15
  },
16
16
  "database": { "pooling": "transaction" },
17
+ "storage": true,
17
18
  "generate": ["__PREFIX___AUTH_SECRET"],
18
19
  "core": ">=0.49.0 <1.0.0"
19
20
  }