@sovereignfs/create 0.14.0 → 0.17.1

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 CHANGED
@@ -10,7 +10,8 @@ npm create @sovereignfs my-instance
10
10
  ```
11
11
 
12
12
  Then `./sv setup`. `npm create @sovereignfs app my-notes` makes a Next.js app that an instance can host as it stands: it signs in through
13
- the instance's core, keeps its data in its own database, and builds into an image whose label is its manifest. See [`@sovereignfs/cli`](https://www.npmjs.com/package/@sovereignfs/cli). Licence: AGPL-3.0-or-later.
13
+ the instance's core, keeps its data in its own database, and builds into an image whose label is its manifest. With `--encryption`, its
14
+ notes are encrypted in the browser and shared between people of the instance (not yet audited; see its `ENCRYPTION.md`). See [`@sovereignfs/cli`](https://www.npmjs.com/package/@sovereignfs/cli). Licence: AGPL-3.0-or-later.
14
15
 
15
16
  Once an app exists, it keeps the files every app of the suite shares (its release workflows, repository settings, contributing and
16
17
  release guides, and the shared section of `AGENTS.md`) with the version of this package it pins:
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.14.0",
10
+ version: "0.17.1",
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",
@@ -152,6 +152,7 @@ function readRequest(argv, env) {
152
152
  let kind;
153
153
  let remote;
154
154
  let port;
155
+ let encryption = false;
155
156
  const words = [];
156
157
  for (let i = 0; i < argv.length; i += 1) {
157
158
  const word = argv[i];
@@ -161,11 +162,12 @@ function readRequest(argv, env) {
161
162
  else if (word.startsWith("--remote=")) remote = word.slice("--remote=".length);
162
163
  else if (word === "--port") port = argv[++i] ?? "";
163
164
  else if (word.startsWith("--port=")) port = word.slice("--port=".length);
165
+ else if (word === "--encryption") encryption = true;
164
166
  else if (word.startsWith("--"))
165
167
  throw new CreateError(
166
168
  `There is no option ${word}.`,
167
169
  2,
168
- "Use: npm create @sovereignfs instance <folder> [--remote URL], or app <folder> [--port N]"
170
+ "Use: npm create @sovereignfs instance <folder> [--remote URL], or app <folder> [--port N] [--encryption]"
169
171
  );
170
172
  else words.push(word);
171
173
  }
@@ -183,7 +185,15 @@ function readRequest(argv, env) {
183
185
  "Use: npm create @sovereignfs instance <folder>"
184
186
  );
185
187
  port ??= env.npm_config_port === void 0 || env.npm_config_port === "" ? void 0 : env.npm_config_port;
186
- return { kind, dir: words[0], remote, port: port === void 0 ? void 0 : parsePort(port) };
188
+ const flag = env.npm_config_encryption;
189
+ if (flag !== void 0 && flag !== "" && flag !== "false") encryption = true;
190
+ return {
191
+ kind,
192
+ dir: words[0],
193
+ remote,
194
+ port: port === void 0 ? void 0 : parsePort(port),
195
+ encryption
196
+ };
187
197
  }
188
198
  async function checkEmpty(dir) {
189
199
  try {
@@ -266,6 +276,9 @@ async function createInstance(request, io2, exec2, cwd) {
266
276
  import path2 from "path";
267
277
  import { fileURLToPath } from "url";
268
278
  var TEMPLATE = fileURLToPath(new URL("../template/app", import.meta.url));
279
+ var ENCRYPTION_TEMPLATE = fileURLToPath(
280
+ new URL("../template/encryption", import.meta.url)
281
+ );
269
282
  var RENAMED = {
270
283
  _gitignore: ".gitignore",
271
284
  _dockerignore: ".dockerignore",
@@ -309,15 +322,18 @@ var APP_DEPENDENCIES = {
309
322
  "@sovereignfs/config": "^0.1.0",
310
323
  "@sovereignfs/sdk": "^2.0.0",
311
324
  "@sovereignfs/storage": "^0.1.0",
312
- "@sovereignfs/ui": "^0.96.1",
325
+ "@sovereignfs/ui": "^0.99.0",
313
326
  next: "^16.4.6",
314
327
  pg: "^8.23.1",
315
328
  react: "^19.3.1",
316
329
  "react-dom": "^19.3.1"
317
330
  };
331
+ var ENCRYPTION_DEPENDENCIES = {
332
+ "@sovereignfs/sdk": "^2.5.0"
333
+ };
318
334
  var APP_DEV_DEPENDENCIES = {
319
335
  // Makes the image's label and port from the manifest, and checks the manifest (`sovereign-manifest`).
320
- "@sovereignfs/manifest": "^0.2.0",
336
+ "@sovereignfs/manifest": "^0.3.0",
321
337
  "@types/node": "^24.19.2",
322
338
  "@types/pg": "^8.23.1",
323
339
  "@types/react": "^19.3.0",
@@ -363,7 +379,7 @@ async function* walk(dir, base = dir) {
363
379
  else yield path3.relative(base, full);
364
380
  }
365
381
  }
366
- function appPackageJson(names, port = DEFAULT_APP_PORT) {
382
+ function appPackageJson(names, port = DEFAULT_APP_PORT, options = {}) {
367
383
  return `${JSON.stringify(
368
384
  {
369
385
  // Every app of the suite is named in the @sovereignfs scope. It is private, so the name claims nothing on npm.
@@ -384,7 +400,7 @@ function appPackageJson(names, port = DEFAULT_APP_PORT) {
384
400
  // Turns the versioned hooks on for whoever installs; harmless where there is no repository (the image's build).
385
401
  prepare: "git config core.hooksPath .githooks || true"
386
402
  },
387
- dependencies: APP_DEPENDENCIES,
403
+ dependencies: options.encryption ? { ...APP_DEPENDENCIES, ...ENCRYPTION_DEPENDENCIES } : APP_DEPENDENCIES,
388
404
  // `@sovereignfs/create` is pinned exactly: `npm create @sovereignfs sync` and the shared workflows run this version (research 0007).
389
405
  devDependencies: { ...APP_DEV_DEPENDENCIES, "@sovereignfs/create": CREATE_VERSION },
390
406
  // What the shared files need of this app: its tag prefix, the checks its main requires, and any shared file it keeps as its own.
@@ -395,34 +411,38 @@ function appPackageJson(names, port = DEFAULT_APP_PORT) {
395
411
  )}
396
412
  `;
397
413
  }
398
- async function writeApp(target, names, port = DEFAULT_APP_PORT) {
414
+ async function writeApp(target, names, port = DEFAULT_APP_PORT, options = {}) {
399
415
  await checkEmpty(target);
400
- const written = [];
416
+ const written = /* @__PURE__ */ new Set();
401
417
  const values = { names, port, workflowsRef: SHARED_WORKFLOWS_REF, directory: ".", tagPrefix: "" };
402
418
  const replace = (text2) => fill(text2, values);
403
- for await (const file of walk(TEMPLATE)) {
404
- const out = targetOf(file);
405
- const target_ = path3.join(target, out);
406
- await mkdir2(path3.dirname(target_), { recursive: true });
407
- let text2 = replace(await readFile(path3.join(TEMPLATE, file), "utf8"));
408
- if (out === "sovereign.manifest.json") text2 = text2.replace(/"port": \d+/, `"port": ${port}`);
409
- if (out === path3.join(".github", "repository.json"))
410
- text2 = repositorySettings(text2, DEFAULT_REQUIRED_CHECKS);
411
- await writeFile2(target_, text2, {
412
- mode: out.startsWith(`.githooks${path3.sep}`) ? 493 : 420
413
- });
414
- written.push(out);
415
- }
416
- await writeFile2(path3.join(target, "package.json"), appPackageJson(names, port));
417
- written.push("package.json");
418
- return written.sort();
419
+ const sources = [TEMPLATE, ...options.encryption ? [ENCRYPTION_TEMPLATE] : []];
420
+ for (const source of sources)
421
+ for await (const file of walk(source)) {
422
+ const out = targetOf(file);
423
+ const target_ = path3.join(target, out);
424
+ await mkdir2(path3.dirname(target_), { recursive: true });
425
+ let text2 = replace(await readFile(path3.join(source, file), "utf8"));
426
+ if (out === "sovereign.manifest.json") text2 = text2.replace(/"port": \d+/, `"port": ${port}`);
427
+ if (out === path3.join(".github", "repository.json"))
428
+ text2 = repositorySettings(text2, DEFAULT_REQUIRED_CHECKS);
429
+ await writeFile2(target_, text2, {
430
+ mode: out.startsWith(`.githooks${path3.sep}`) ? 493 : 420
431
+ });
432
+ written.add(out);
433
+ }
434
+ await writeFile2(path3.join(target, "package.json"), appPackageJson(names, port, options));
435
+ written.add("package.json");
436
+ return [...written].sort();
419
437
  }
420
438
  async function createApp(request, io2, exec2, cwd) {
421
439
  const target = path3.resolve(cwd, request.dir);
422
440
  const names = namesOf(target);
423
441
  const port = request.port ?? DEFAULT_APP_PORT;
424
- const written = await writeApp(target, names, port);
425
- io2.err(`Wrote the files of ${names.name}, on port ${port}.`);
442
+ const written = await writeApp(target, names, port, { encryption: request.encryption ?? false });
443
+ io2.err(
444
+ `Wrote the files of ${names.name}, on port ${port}${request.encryption ? ", with its notes encrypted" : ""}.`
445
+ );
426
446
  const step = async (label, command, args, hint) => {
427
447
  const done = await exec2(command, args, { cwd: target });
428
448
  if (done.code !== 0) {
@@ -1330,8 +1350,10 @@ async function main() {
1330
1350
  const answer = await io.ask(`Which port should it listen on? (${DEFAULT_APP_PORT})`);
1331
1351
  port = answer === "" ? DEFAULT_APP_PORT : parsePort(answer);
1332
1352
  }
1333
- await createApp({ dir, port }, io, exec, process.cwd());
1353
+ await createApp({ dir, port, encryption: request.encryption }, io, exec, process.cwd());
1334
1354
  } else {
1355
+ if (request.encryption)
1356
+ throw new CreateError("--encryption is for an app.", 2, "Make an app with it instead.");
1335
1357
  if (request.port !== void 0)
1336
1358
  throw new CreateError(
1337
1359
  "--port is for an app.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sovereignfs/create",
3
- "version": "0.14.0",
3
+ "version": "0.17.1",
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",
@@ -0,0 +1,30 @@
1
+ # Encryption in **TITLE**
2
+
3
+ This app was made with `--encryption`: its notes are encrypted in the browser, so that someone who reads the server, its database or a
4
+ backup cannot read them. **Not yet audited:** Sovereign's encryption has not yet been reviewed by a cryptographer or audited, so say so
5
+ wherever you describe it, and never promise more than this file does. The rules are Sovereign's guide, _Encrypting an app's data_.
6
+
7
+ ## What it protects, and what it does not
8
+
9
+ - **Protected:** a note's title and text, from anyone who reads the server's disk, its database or a backup.
10
+ - **Not protected:** anything against whoever runs the server, since the pages come from it; files (the Files card says so); and who
11
+ shares with whom, sizes and times, which the server sees.
12
+
13
+ ## How it works
14
+
15
+ - **The app's key** comes from the person's Sovereign once each browser session (`appKeys` from `@sovereignfs/sdk/keys`): `/keys/return`
16
+ is the key return address in `sovereign.manifest.json` (`encryption`), and the operator allows the app when hosting it.
17
+ - **Each note has a key of its own**, sealed to each person who may read it, the owner included, and signed by the owner (`share`). Its
18
+ title and text are encrypted with it (`encryptBytes`), bound to the note's id and version.
19
+ - **The server** (`lib/notes.ts`, `app/api/notes`) stores what the page sends and opens nothing. Every statement names the person.
20
+ - **Sharing** looks people up in the instance's Directory and checks their keys against their account's signature (`checkPerson`). A
21
+ person whose keys changed is shown as such, and is shared with only if the person sharing says so.
22
+ - **Removing someone** makes a new key for the note, sealed only to those who remain. What they already read cannot be taken back, and
23
+ the dialog says so.
24
+ - **A deleted account** takes its notes and every key sealed to it (`lib/auth.ts`).
25
+
26
+ ## Rules to keep as the app grows (RFC 0005 §8)
27
+
28
+ - Nothing of a note in a notification, an activity entry or mail sent through core.
29
+ - Never show ciphertext: show `LockedState` where the browser is locked.
30
+ - Nothing of a note in a log, an error or analytics.
@@ -0,0 +1,20 @@
1
+ 'use server';
2
+
3
+ import { revalidatePath } from 'next/cache';
4
+ import { auth } from '@/lib/auth';
5
+ import { files } from '@/lib/files';
6
+ import { StorageError } from '@sovereignfs/storage';
7
+
8
+ // The notes are written by the page itself, encrypted, through /api/notes (app/notes.tsx): the server never sees them in the clear.
9
+
10
+ /** Every server action is a public POST endpoint, so each one asks who is calling before it does anything. */
11
+ export async function deleteFile(formData: FormData): Promise<void> {
12
+ const session = await auth().requireSession('/');
13
+ try {
14
+ // 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.
15
+ await files().remove(session.sub, String(formData.get('id') ?? ''));
16
+ } catch (error) {
17
+ if (!(error instanceof StorageError && error.code === 'not_found')) throw error;
18
+ }
19
+ revalidatePath('/');
20
+ }
@@ -0,0 +1,21 @@
1
+ import { CoreApiError } from '@sovereignfs/sdk';
2
+ import { auth } from '@/lib/auth';
3
+ import { unauthorised } from '@/lib/files';
4
+ import { sovereign } from '@/lib/sovereign';
5
+
6
+ export const dynamic = 'force-dynamic';
7
+
8
+ /** The signed-in person's own keys for this app (sdk §8): public keys, and private keys the server cannot open. */
9
+ export async function GET() {
10
+ const session = await auth().getSession();
11
+ if (!session) return unauthorised();
12
+ try {
13
+ const keys = await sovereign().as({ sub: session.sub }).keys.me();
14
+ return Response.json(keys, { headers: { 'cache-control': 'no-store' } });
15
+ } catch (error) {
16
+ if (error instanceof CoreApiError && error.status === 404) {
17
+ return Response.json({ error: 'not-opened' }, { status: 404 });
18
+ }
19
+ throw error;
20
+ }
21
+ }
@@ -0,0 +1,39 @@
1
+ import { auth } from '@/lib/auth';
2
+ import { refuseCrossOrigin, unauthorised } from '@/lib/files';
3
+ import { checkWrite, NoteError, notes } from '@/lib/notes';
4
+
5
+ export const dynamic = 'force-dynamic';
6
+
7
+ type Context = { params: Promise<{ id: string }> };
8
+
9
+ const refused = (error: unknown) =>
10
+ error instanceof NoteError
11
+ ? Response.json({ error: error.message }, { status: error.status })
12
+ : undefined;
13
+
14
+ /** Writes one of the signed-in person's notes, new or changed, with everyone who may read it: what the browser encrypted, as it is. */
15
+ export async function PUT(request: Request, { params }: Context) {
16
+ const cross = refuseCrossOrigin(request);
17
+ if (cross) return cross;
18
+ const session = await auth().getSession();
19
+ if (!session) return unauthorised();
20
+ try {
21
+ const note = checkWrite(session.sub, (await params).id, await request.json().catch(() => null));
22
+ await notes().save(session.sub, note);
23
+ return new Response(null, { status: 204 });
24
+ } catch (error) {
25
+ const answer = refused(error);
26
+ if (answer) return answer;
27
+ throw error;
28
+ }
29
+ }
30
+
31
+ /** Deletes one of the signed-in person's notes, and every key sealed for it. */
32
+ export async function DELETE(request: Request, { params }: Context) {
33
+ const cross = refuseCrossOrigin(request);
34
+ if (cross) return cross;
35
+ const session = await auth().getSession();
36
+ if (!session) return unauthorised();
37
+ const removed = await notes().remove(session.sub, (await params).id);
38
+ return new Response(null, { status: removed ? 204 : 404 });
39
+ }
@@ -0,0 +1,36 @@
1
+ import { auth } from '@/lib/auth';
2
+ import { unauthorised } from '@/lib/files';
3
+ import { notes } from '@/lib/notes';
4
+ import { sovereign } from '@/lib/sovereign';
5
+
6
+ export const dynamic = 'force-dynamic';
7
+
8
+ /**
9
+ * The notes the signed-in person can read, encrypted as the browser stored them, with the names of the people they involve (from the
10
+ * instance's Directory) so the page can say who shared what with whom. Nothing here opens a note.
11
+ */
12
+ export async function GET() {
13
+ const session = await auth().getSession();
14
+ if (!session) return unauthorised();
15
+ const list = await notes().list(session.sub);
16
+ const subs = [
17
+ ...new Set(
18
+ list.flatMap((note) => [note.owner, ...note.readers]).filter((s) => s !== session.sub),
19
+ ),
20
+ ];
21
+ let names: Record<string, string> = {};
22
+ if (subs.length > 0) {
23
+ try {
24
+ const { users } = await sovereign()
25
+ .as({ sub: session.sub })
26
+ .directory.resolveUsers({ subs: subs.slice(0, 100) });
27
+ names = Object.fromEntries(users.map((user) => [user.sub, user.name]));
28
+ } catch {
29
+ // Without the Directory the page names nobody, and still opens every note.
30
+ }
31
+ }
32
+ return Response.json(
33
+ { me: session.sub, notes: list, names },
34
+ { headers: { 'cache-control': 'no-store' } },
35
+ );
36
+ }
@@ -0,0 +1,26 @@
1
+ import { CoreApiError } from '@sovereignfs/sdk';
2
+ import { auth } from '@/lib/auth';
3
+ import { unauthorised } from '@/lib/files';
4
+ import { sovereign } from '@/lib/sovereign';
5
+
6
+ export const dynamic = 'force-dynamic';
7
+
8
+ /**
9
+ * Another person's public keys for this app, from core (sdk §8): what the page checks, then seals a note's key to. A 404 when they have
10
+ * never opened this app, since their keys are made then. The page checks the account's signature itself; it does not trust this route.
11
+ */
12
+ export async function GET(_request: Request, { params }: { params: Promise<{ sub: string }> }) {
13
+ const session = await auth().getSession();
14
+ if (!session) return unauthorised();
15
+ try {
16
+ const keys = await sovereign()
17
+ .as({ sub: session.sub })
18
+ .keys.person((await params).sub);
19
+ return Response.json(keys, { headers: { 'cache-control': 'no-store' } });
20
+ } catch (error) {
21
+ if (error instanceof CoreApiError && error.status === 404) {
22
+ return Response.json({ error: 'not-opened' }, { status: 404 });
23
+ }
24
+ throw error;
25
+ }
26
+ }
@@ -0,0 +1,22 @@
1
+ import { auth } from '@/lib/auth';
2
+ import { unauthorised } from '@/lib/files';
3
+ import { sovereign } from '@/lib/sovereign';
4
+
5
+ export const dynamic = 'force-dynamic';
6
+
7
+ /** People on the instance to share with, found by name (or a whole address) in its Directory, as the signed-in person. */
8
+ export async function GET(request: Request) {
9
+ const session = await auth().getSession();
10
+ if (!session) return unauthorised();
11
+ const q = (new URL(request.url).searchParams.get('q') ?? '').trim().slice(0, 100);
12
+ if (q.length < 2) return Response.json({ people: [] });
13
+ const { users } = await sovereign().as({ sub: session.sub }).directory.searchUsers({ q });
14
+ return Response.json(
15
+ {
16
+ people: users
17
+ .filter((user) => user.sub !== session.sub)
18
+ .map((user) => ({ sub: user.sub, name: user.name })),
19
+ },
20
+ { headers: { 'cache-control': 'no-store' } },
21
+ );
22
+ }
@@ -0,0 +1,11 @@
1
+ import { auth } from '@/lib/auth';
2
+ import { keySettings } from '@/lib/keys';
3
+ import { Received } from './received';
4
+
5
+ export const dynamic = 'force-dynamic';
6
+
7
+ /** The key return address (`encryption.return` in the manifest): core sends the person back here with the app's key, sealed. */
8
+ export default async function KeyReturn() {
9
+ await auth().requireSession('/');
10
+ return <Received {...keySettings()} />;
11
+ }
@@ -0,0 +1,36 @@
1
+ 'use client';
2
+
3
+ import { appKeys } from '@sovereignfs/sdk/keys';
4
+ import { useRouter } from 'next/navigation';
5
+ import { useEffect, useState } from 'react';
6
+ import { Alert, Button, Card } from '../../ui';
7
+
8
+ /** Takes core's answer from the address, checks it and keeps the key (sdk §9.3), then goes back to where the person was. */
9
+ export function Received(props: { core: string; clientId: string; returnTo: string }) {
10
+ const router = useRouter();
11
+ const [failed, setFailed] = useState(false);
12
+
13
+ useEffect(() => {
14
+ const keys = appKeys(props);
15
+ keys
16
+ .receive()
17
+ .then((received) => (received.ok ? router.replace(received.returnPath) : setFailed(true)))
18
+ .catch(() => setFailed(true));
19
+ // Once, when the page loads: the answer is in the address only until it is read.
20
+ }, []);
21
+
22
+ if (!failed)
23
+ return (
24
+ <Card>
25
+ <h1>Unlocking…</h1>
26
+ <p>Taking you back to where you were.</p>
27
+ </Card>
28
+ );
29
+ return (
30
+ <Alert variant="error" heading="Couldn’t unlock">
31
+ <p>Try again.</p>
32
+ <Button onClick={() => void appKeys(props).unlock('/')}>Try again</Button>{' '}
33
+ <a href="/">Back to your notes</a>
34
+ </Alert>
35
+ );
36
+ }