@earendil-works/chord 1.4.0 → 1.5.1

package/dist/node/app/info.d.ts

@@ -0,0 +1,66 @@
+import type { Principal } from "../../data/index.ts";
+import { type Facet } from "../../host/index.ts";
+import type { JsonValue } from "../../json.ts";
+/** What the server knows of the app: its data directory, its name, its newest API version, its owner principal. */
+export declare const AppInfo: import("../../contracts/contract.ts").Contract<{
+    kind: "local";
+    name: "chord.app.info";
+    params: {};
+    history: [{
+        version: "2";
+        variants: {
+            members: {
+                state: {
+                    readonly dataDir: import("../../contracts/schema.ts").StringSchema;
+                    readonly name: import("../../contracts/schema.ts").StringSchema;
+                    readonly version: import("../../contracts/schema.ts").StringSchema;
+                    readonly owner: import("../../contracts/index.ts").Schema<unknown>;
+                };
+                methods: {};
+                keyed: {};
+            };
+        };
+        changes: never;
+    }];
+}>;
+/** What a worker knows of itself: its address (kind, params, key) and the app's start data for it. */
+export declare const WorkerInfo: import("../../contracts/contract.ts").Contract<{
+    kind: "local";
+    name: "chord.app.worker-info";
+    params: {};
+    history: [{
+        version: "1";
+        variants: {
+            members: {
+                state: {
+                    readonly address: import("../../contracts/index.ts").Schema<{
+                        kind: string;
+                        key: string;
+                        params: unknown;
+                    }>;
+                    readonly start: import("../../contracts/index.ts").Schema<unknown>;
+                };
+                methods: {};
+                keyed: {};
+            };
+        };
+        changes: never;
+    }];
+}>;
+/** The facet serving `AppInfo` with `info`. */
+export declare function appInfoFacet<P extends Principal>(info: {
+    readonly dataDir: string;
+    readonly name: string;
+    readonly version: string;
+    readonly owner: P;
+}): Facet<P>;
+/** The facet serving `WorkerInfo` with the worker's address and start data. */
+export declare function workerInfoFacet<P extends Principal>(info: {
+    readonly address: {
+        readonly kind: string;
+        readonly key: string;
+        readonly params: JsonValue;
+    };
+    readonly start: JsonValue;
+}): Facet<P>;
+//# sourceMappingURL=info.d.ts.map

package/dist/node/app/info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"info.d.ts","sourceRoot":"","sources":["../../../src/node/app/info.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG/C,mHAAmH;AACnH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;EAIlB,CAAC;AAEH,sGAAsG;AACtG,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;EAOrB,CAAC;AAEH,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CAClB,GAAG,KAAK,CAAC,CAAC,CAAC,CAUX;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE;IAC1D,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC;IAC9F,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC1B,GAAG,KAAK,CAAC,CAAC,CAAC,CAIX"}

package/dist/node/app/info.js

@@ -0,0 +1,37 @@
+// The start-data objects (slice 13 §1; decision "The plugin model, points 3, 4, 5 and 8" (8)): base code shrinks to
+// the API, the bootstrap and one facet serving process values as core objects plugins `get`. `AppInfo` on the
+// server (the data directory, the app's name, its API version and its owner: decision "The kit's owner is a principal
+// the app chooses"), `WorkerInfo` on a worker (its address and the app's start data for it).
+import { local, obj, str, unknown } from "../../contracts/index.js";
+import { defineFacet } from "../../host/index.js";
+import { constant } from "../../state/index.js";
+/** What the server knows of the app: its data directory, its name, its newest API version, its owner principal. */
+export const AppInfo = local("chord.app.info", {
+    version: 2,
+    params: {},
+    members: { dataDir: str(), name: str(), version: str(), owner: unknown() },
+});
+/** What a worker knows of itself: its address (kind, params, key) and the app's start data for it. */
+export const WorkerInfo = local("chord.app.worker-info", {
+    version: 1,
+    params: {},
+    members: {
+        address: obj({ kind: str(), key: str(), params: unknown() }),
+        start: unknown(),
+    },
+});
+/** The facet serving `AppInfo` with `info`. */
+export function appInfoFacet(info) {
+    return defineFacet((host) => host.serve(AppInfo, () => ({
+        dataDir: constant(info.dataDir),
+        name: constant(info.name),
+        version: constant(info.version),
+        // The same object at every get: its principal key is computed once.
+        owner: constant(info.owner),
+    })));
+}
+/** The facet serving `WorkerInfo` with the worker's address and start data. */
+export function workerInfoFacet(info) {
+    return defineFacet((host) => host.serve(WorkerInfo, () => ({ address: constant(info.address), start: constant(info.start) })));
+}
+//# sourceMappingURL=info.js.map

package/dist/node/app/info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"info.js","sourceRoot":"","sources":["../../../src/node/app/info.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,8GAA8G;AAC9G,sHAAsH;AACtH,6FAA6F;AAE7F,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAc,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,mHAAmH;AACnH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,CAAC,gBAAgB,EAAE;IAC9C,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;CAC1E,CAAC,CAAC;AAEH,sGAAsG;AACtG,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,CAAC,uBAAuB,EAAE;IACxD,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,EAAE;IACV,OAAO,EAAE;QACR,OAAO,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;QAC5D,KAAK,EAAE,OAAO,EAAE;KAChB;CACD,CAAC,CAAC;AAEH,+CAA+C;AAC/C,MAAM,UAAU,YAAY,CAAsB,IAKjD;IACA,OAAO,WAAW,CAAI,CAAC,IAAI,EAAE,EAAE,CAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QAC1B,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;QAC/B,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QACzB,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;QAC/B,oEAAoE;QACpE,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;KAC3B,CAAC,CAAC,CACH,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAsB,IAGpD;IACA,OAAO,WAAW,CAAI,CAAC,IAAI,EAAE,EAAE,CAC9B,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAChG,CAAC;AACH,CAAC","sourcesContent":["// The start-data objects (slice 13 §1; decision \"The plugin model, points 3, 4, 5 and 8\" (8)): base code shrinks to\n// the API, the bootstrap and one facet serving process values as core objects plugins `get`. `AppInfo` on the\n// server (the data directory, the app's name, its API version and its owner: decision \"The kit's owner is a principal\n// the app chooses\"), `WorkerInfo` on a worker (its address and the app's start data for it).\n\nimport { local, obj, str, unknown } from \"../../contracts/index.ts\";\nimport type { Principal } from \"../../data/index.ts\";\nimport { defineFacet, type Facet } from \"../../host/index.ts\";\nimport type { JsonValue } from \"../../json.ts\";\nimport { constant } from \"../../state/index.ts\";\n\n/** What the server knows of the app: its data directory, its name, its newest API version, its owner principal. */\nexport const AppInfo = local(\"chord.app.info\", {\n\tversion: 2,\n\tparams: {},\n\tmembers: { dataDir: str(), name: str(), version: str(), owner: unknown() },\n});\n\n/** What a worker knows of itself: its address (kind, params, key) and the app's start data for it. */\nexport const WorkerInfo = local(\"chord.app.worker-info\", {\n\tversion: 1,\n\tparams: {},\n\tmembers: {\n\t\taddress: obj({ kind: str(), key: str(), params: unknown() }),\n\t\tstart: unknown(),\n\t},\n});\n\n/** The facet serving `AppInfo` with `info`. */\nexport function appInfoFacet<P extends Principal>(info: {\n\treadonly dataDir: string;\n\treadonly name: string;\n\treadonly version: string;\n\treadonly owner: P;\n}): Facet<P> {\n\treturn defineFacet<P>((host) =>\n\t\thost.serve(AppInfo, () => ({\n\t\t\tdataDir: constant(info.dataDir),\n\t\t\tname: constant(info.name),\n\t\t\tversion: constant(info.version),\n\t\t\t// The same object at every get: its principal key is computed once.\n\t\t\towner: constant(info.owner),\n\t\t})),\n\t);\n}\n\n/** The facet serving `WorkerInfo` with the worker's address and start data. */\nexport function workerInfoFacet<P extends Principal>(info: {\n\treadonly address: { readonly kind: string; readonly key: string; readonly params: JsonValue };\n\treadonly start: JsonValue;\n}): Facet<P> {\n\treturn defineFacet<P>((host) =>\n\t\thost.serve(WorkerInfo, () => ({ address: constant(info.address), start: constant(info.start) })),\n\t);\n}\n"]}

package/dist/node/app/invite.d.ts

@@ -0,0 +1,5 @@
+import type { Principal } from "../../data/index.ts";
+import { type Facet } from "../../host/index.ts";
+/** The invite plugin's server facet; the owner (`AppInfo.owner`) makes the invites. */
+export declare function inviteFacet<P extends Principal>(): Facet<P>;
+//# sourceMappingURL=invite.d.ts.map

package/dist/node/app/invite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invite.d.ts","sourceRoot":"","sources":["../../../src/node/app/invite.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAiB9D,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,CAiD3D"}

package/dist/node/app/invite.js

@@ -0,0 +1,64 @@
+// The invite plugin (slice 13 §3, decision "The app kit, point 2"): the owner (`AppInfo.owner`, the principal the app
+// names) makes an invite link for a principal of the app it chooses (`POST /_chord/invites`, owner only: `{ principal,
+// label }` → `{ path }`); the invitee opens it, its page posts the token (the URL's fragment, never logged) to `POST
+// /_chord/invite`, which consumes it (single use, 7 days) and answers with a browser session for that principal (§2's
+// sessions). Invites wait in memory: a restart drops the ones not used. An exported facet, as `defineUsers` (see there
+// why).
+import { samePrincipal } from "../../data/principal.js";
+import { defineFacet } from "../../host/index.js";
+import { Http } from "../http/index.js";
+import { AppInfo } from "./info.js";
+import { fragmentPage } from "./owner.js";
+import { hashToken, newToken } from "./secrets.js";
+import { Sessions } from "./sessions.js";
+/** How long an invite is valid: 7 days. */
+const INVITE_MS = 7 * 24 * 60 * 60_000;
+/** The invite link's path: its page, and the post that consumes it. */
+const INVITE_PATH = "/_chord/invite";
+/** The invite plugin's server facet; the owner (`AppInfo.owner`) makes the invites. */
+export function inviteFacet() {
+    // By their token's hash: what the map holds is no credential.
+    const invites = new Map();
+    return defineFacet((_host, self) => self.contribute(Http, {
+        routes: {
+            "POST /_chord/invites": async (request, ctx) => {
+                // `AppInfo.owner` is the app's `principal.owner`, a principal of its type.
+                const owner = (await ctx.get(AppInfo, {})).owner.value;
+                if (!samePrincipal(ctx.principal, owner, ctx))
+                    return { kind: "error", status: 403 };
+                // A trust boundary: the owner's request, checked for its shape.
+                const body = (await request.json());
+                const principal = body?.principal;
+                if (typeof principal !== "object" || principal === null || typeof body?.label !== "string") {
+                    return { kind: "error", status: 400 };
+                }
+                const token = newToken();
+                invites.set(hashToken(token), { principal, label: body.label, expires: Date.now() + INVITE_MS });
+                return { kind: "json", value: { path: `${INVITE_PATH}#${token}` } };
+            },
+            [`GET ${INVITE_PATH}`]: {
+                public: true,
+                handler: async (request) => ({ kind: "html", body: fragmentPage(INVITE_PATH, request.nonce) }),
+            },
+            [`POST ${INVITE_PATH}`]: {
+                public: true,
+                handler: async (request, ctx) => {
+                    // A trust boundary: anyone may post here.
+                    const body = (await request.json());
+                    const hash = typeof body?.token === "string" ? hashToken(body.token) : undefined;
+                    const invite = hash === undefined ? undefined : invites.get(hash);
+                    if (hash === undefined || invite === undefined)
+                        return { kind: "error", status: 403 };
+                    invites.delete(hash);
+                    if (invite.expires <= Date.now())
+                        return { kind: "error", status: 403 };
+                    const sessions = await ctx.get(Sessions, {});
+                    const secure = request.provenance.kind !== "local";
+                    const issued = await sessions.issue({ principal: invite.principal, label: invite.label, kind: "browser", secure }, ctx);
+                    return { kind: "json", value: "signed in", headers: { "Set-Cookie": issued.cookie } };
+                },
+            },
+        },
+    }));
+}
+//# sourceMappingURL=invite.js.map

package/dist/node/app/invite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invite.js","sourceRoot":"","sources":["../../../src/node/app/invite.ts"],"names":[],"mappings":"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","sourcesContent":["// The invite plugin (slice 13 §3, decision \"The app kit, point 2\"): the owner (`AppInfo.owner`, the principal the app\n// names) makes an invite link for a principal of the app it chooses (`POST /_chord/invites`, owner only: `{ principal,\n// label }` → `{ path }`); the invitee opens it, its page posts the token (the URL's fragment, never logged) to `POST\n// /_chord/invite`, which consumes it (single use, 7 days) and answers with a browser session for that principal (§2's\n// sessions). Invites wait in memory: a restart drops the ones not used. An exported facet, as `defineUsers` (see there\n// why).\n\nimport type { Principal } from \"../../data/index.ts\";\nimport { samePrincipal } from \"../../data/principal.ts\";\nimport { defineFacet, type Facet } from \"../../host/index.ts\";\nimport type { JsonValue } from \"../../json.ts\";\nimport { Http } from \"../http/index.ts\";\nimport { AppInfo } from \"./info.ts\";\nimport { fragmentPage } from \"./owner.ts\";\nimport { hashToken, newToken } from \"./secrets.ts\";\nimport { Sessions } from \"./sessions.ts\";\n\n/** How long an invite is valid: 7 days. */\nconst INVITE_MS = 7 * 24 * 60 * 60_000;\n\n/** The invite link's path: its page, and the post that consumes it. */\nconst INVITE_PATH = \"/_chord/invite\";\n\n/** An invite waiting: the principal it signs in, its label, its expiry. */\ntype Invite = { readonly principal: JsonValue; readonly label: string; readonly expires: number };\n\n/** The invite plugin's server facet; the owner (`AppInfo.owner`) makes the invites. */\nexport function inviteFacet<P extends Principal>(): Facet<P> {\n\t// By their token's hash: what the map holds is no credential.\n\tconst invites = new Map<string, Invite>();\n\treturn defineFacet<P>((_host, self) =>\n\t\tself.contribute(Http, {\n\t\t\troutes: {\n\t\t\t\t\"POST /_chord/invites\": async (request, ctx) => {\n\t\t\t\t\t// `AppInfo.owner` is the app's `principal.owner`, a principal of its type.\n\t\t\t\t\tconst owner = (await ctx.get(AppInfo, {})).owner.value as Principal;\n\t\t\t\t\tif (!samePrincipal(ctx.principal, owner, ctx)) return { kind: \"error\", status: 403 };\n\t\t\t\t\t// A trust boundary: the owner's request, checked for its shape.\n\t\t\t\t\tconst body = (await request.json()) as {\n\t\t\t\t\t\treadonly principal?: JsonValue;\n\t\t\t\t\t\treadonly label?: unknown;\n\t\t\t\t\t} | null;\n\t\t\t\t\tconst principal = body?.principal;\n\t\t\t\t\tif (typeof principal !== \"object\" || principal === null || typeof body?.label !== \"string\") {\n\t\t\t\t\t\treturn { kind: \"error\", status: 400 };\n\t\t\t\t\t}\n\t\t\t\t\tconst token = newToken();\n\t\t\t\t\tinvites.set(hashToken(token), { principal, label: body.label, expires: Date.now() + INVITE_MS });\n\t\t\t\t\treturn { kind: \"json\", value: { path: `${INVITE_PATH}#${token}` } };\n\t\t\t\t},\n\t\t\t\t[`GET ${INVITE_PATH}`]: {\n\t\t\t\t\tpublic: true,\n\t\t\t\t\thandler: async (request) => ({ kind: \"html\", body: fragmentPage(INVITE_PATH, request.nonce) }),\n\t\t\t\t},\n\t\t\t\t[`POST ${INVITE_PATH}`]: {\n\t\t\t\t\tpublic: true,\n\t\t\t\t\thandler: async (request, ctx) => {\n\t\t\t\t\t\t// A trust boundary: anyone may post here.\n\t\t\t\t\t\tconst body = (await request.json()) as { readonly token?: unknown } | null;\n\t\t\t\t\t\tconst hash = typeof body?.token === \"string\" ? hashToken(body.token) : undefined;\n\t\t\t\t\t\tconst invite = hash === undefined ? undefined : invites.get(hash);\n\t\t\t\t\t\tif (hash === undefined || invite === undefined) return { kind: \"error\", status: 403 };\n\t\t\t\t\t\tinvites.delete(hash);\n\t\t\t\t\t\tif (invite.expires <= Date.now()) return { kind: \"error\", status: 403 };\n\t\t\t\t\t\tconst sessions = await ctx.get(Sessions, {});\n\t\t\t\t\t\tconst secure = request.provenance.kind !== \"local\";\n\t\t\t\t\t\tconst issued = await sessions.issue(\n\t\t\t\t\t\t\t{ principal: invite.principal, label: invite.label, kind: \"browser\", secure },\n\t\t\t\t\t\t\tctx,\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn { kind: \"json\", value: \"signed in\", headers: { \"Set-Cookie\": issued.cookie } };\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t}),\n\t);\n}\n"]}

package/dist/node/app/layout.d.ts

@@ -0,0 +1,36 @@
+import type { Address } from "../../contracts/index.ts";
+/** The paths of a data directory. */
+export type AppLayout = {
+    readonly dataDir: string;
+    readonly server: string;
+    readonly serverStore: string;
+    readonly workers: string;
+    readonly plugins: string;
+    readonly logs: string;
+    /** Each worker kind's base, in `<kind>/` (`WorkersOptions.baseDir`): written again at every start. */
+    readonly workerBases: string;
+    /** Node's compile cache for the workers (`NODE_COMPILE_CACHE`). */
+    readonly compileCache: string;
+    readonly ownerToken: string;
+    readonly cookieSecret: string;
+};
+/** The data directory of app `name` unless the start script names one: `~/.<name>`. */
+export declare function defaultDataDir(name: string): string;
+/**
+ * The real path of the data directory `path`, made when missing (mode 0700), refused when the kit must not make it
+ * private: the home directory, a file system's root, or a directory another user owns (a clear error, instead of
+ * tightening a directory others use or failing on `EPERM`). Its mode is set on the real path, never through a link.
+ */
+export declare function openDataDir(path: string): Promise<string>;
+/** The layout of `dataDir` (a real path, `openDataDir`'s), its directories made private (`privateDirectory`). */
+export declare function createLayout(dataDir: string): Promise<AppLayout>;
+/** Makes `dir` (and missing parents) with mode 0700, and sets 0700 on it when it existed. */
+export declare function privateDirectory(dir: string): Promise<void>;
+/**
+ * Makes the store file `path` private before SQLite opens it: created empty with mode 0600 when missing (SQLite gives
+ * its journal files the database's mode), else set to 0600 with the journal files it has.
+ */
+export declare function privateStore(path: string): Promise<void>;
+/** The directory of the worker at `address`: `workers/<kind>/<its key, encoded>`. */
+export declare function workerDirectory(dataDir: string, address: Address): string;
+//# sourceMappingURL=layout.d.ts.map

package/dist/node/app/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/node/app/layout.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAExD,qCAAqC;AACrC,MAAM,MAAM,SAAS,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sGAAsG;IACtG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAa/D;AAED,iHAAiH;AACjH,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAiBtE;AAED,6FAA6F;AAC7F,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjE;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9D;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAEzE"}

package/dist/node/app/layout.js

@@ -0,0 +1,87 @@
+// The app kit's data directory (slice 13 §4, decision "The app kit, point 4: storage"): one fixed layout, made private
+// at every start. `server/` holds the server's store and files, `workers/<kind>/<address>/` each worker's store and
+// files, `plugins/` the user's plugins root, `logs/` the logs, `cache/` what only saves time (`workers/<kind>/`, each
+// worker kind's base, written again at every start; `node/`, the workers' compile cache), `owner-token` the owner's token for command-line
+// clients. Directories are 0700 and stores 0600, also when they existed looser before (other local users must not
+// read the sessions in a store, nor replace it).
+import { createHash } from "node:crypto";
+import { chmod, mkdir, open, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, parse } from "node:path";
+/** The data directory of app `name` unless the start script names one: `~/.<name>`. */
+export function defaultDataDir(name) {
+    return join(homedir(), `.${name}`);
+}
+/**
+ * The real path of the data directory `path`, made when missing (mode 0700), refused when the kit must not make it
+ * private: the home directory, a file system's root, or a directory another user owns (a clear error, instead of
+ * tightening a directory others use or failing on `EPERM`). Its mode is set on the real path, never through a link.
+ */
+export async function openDataDir(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const dataDir = await realpath(path);
+    const home = await realpath(homedir());
+    if (dataDir === home || dataDir === parse(dataDir).root) {
+        const what = dataDir === home ? "the home directory" : "a file system's root";
+        throw new Error(`startServer: the data directory ${dataDir} is ${what}; name a directory of the app's own`);
+    }
+    const { uid } = await stat(dataDir);
+    if (process.getuid !== undefined && uid !== process.getuid()) {
+        throw new Error(`startServer: the data directory ${dataDir} belongs to another user (uid ${uid})`);
+    }
+    return dataDir;
+}
+/** The layout of `dataDir` (a real path, `openDataDir`'s), its directories made private (`privateDirectory`). */
+export async function createLayout(dataDir) {
+    await privateDirectory(dataDir);
+    const layout = {
+        dataDir,
+        server: join(dataDir, "server"),
+        serverStore: join(dataDir, "server", "store.sqlite"),
+        workers: join(dataDir, "workers"),
+        plugins: join(dataDir, "plugins"),
+        logs: join(dataDir, "logs"),
+        workerBases: join(dataDir, "cache", "workers"),
+        compileCache: join(dataDir, "cache", "node"),
+        ownerToken: join(dataDir, "owner-token"),
+        cookieSecret: join(dataDir, "server", "cookie-secret"),
+    };
+    const dirs = [layout.server, layout.workers, layout.plugins, layout.logs, join(dataDir, "cache")];
+    for (const dir of [...dirs, layout.workerBases, layout.compileCache])
+        await privateDirectory(dir);
+    return layout;
+}
+/** Makes `dir` (and missing parents) with mode 0700, and sets 0700 on it when it existed. */
+export async function privateDirectory(dir) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+}
+/**
+ * Makes the store file `path` private before SQLite opens it: created empty with mode 0600 when missing (SQLite gives
+ * its journal files the database's mode), else set to 0600 with the journal files it has.
+ */
+export async function privateStore(path) {
+    await (await open(path, "a", 0o600)).close();
+    for (const file of [path, `${path}-wal`, `${path}-shm`]) {
+        await chmod(file, 0o600).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw error;
+        });
+    }
+}
+/** The directory of the worker at `address`: `workers/<kind>/<its key, encoded>`. */
+export function workerDirectory(dataDir, address) {
+    return join(dataDir, "workers", address.kind, encodedKey(address.key));
+}
+/** The longest key kept readable as a directory name; a longer one is named by its hash. */
+const READABLE_KEY = 160;
+/**
+ * An address key as one directory name: percent-encoded (`/`, `\`, `.` and every other character a file system might
+ * treat specially included), or its SHA-256 when that is longer than `READABLE_KEY`. Capital letters are encoded too:
+ * on a case-insensitive file system (macOS) `p|A` and `p|a` would otherwise share a directory.
+ */
+function encodedKey(key) {
+    const encoded = encodeURIComponent(key).replace(/(%[0-9A-F]{2})|[.!'()*~A-Z]/g, (match, escaped) => escaped ?? `%${match.charCodeAt(0).toString(16).toUpperCase()}`);
+    return encoded.length <= READABLE_KEY ? encoded : `sha256-${createHash("sha256").update(key).digest("hex")}`;
+}
+//# sourceMappingURL=layout.js.map

package/dist/node/app/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../../src/node/app/layout.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,oHAAoH;AACpH,sHAAsH;AACtH,2IAA2I;AAC3I,kHAAkH;AAClH,iDAAiD;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAmBxC,uFAAuF;AACvF,MAAM,UAAU,cAAc,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC7C,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QACzD,MAAM,IAAI,GAAG,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,sBAAsB,CAAC;QAC9E,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,OAAO,IAAI,qCAAqC,CAAC,CAAC;IAC7G,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,iCAAiC,GAAG,GAAG,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC;AAED,iHAAiH;AACjH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAe;IACjD,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,MAAM,GAAc;QACzB,OAAO;QACP,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC;QAC/B,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC;QACpD,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC;QACjC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC;QACjC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC;QAC3B,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC;QAC9C,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC;QAC5C,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC;QACxC,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,eAAe,CAAC;KACtD,CAAC;IACF,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAClG,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,YAAY,CAAC;QAAE,MAAM,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAClG,OAAO,MAAM,CAAC;AACf,CAAC;AAED,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAW;IACjD,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACnD,MAAM,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC9C,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;QACzD,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,KAA4B,EAAE,EAAE;YAC/D,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAC;QAC1C,CAAC,CAAC,CAAC;IACJ,CAAC;AACF,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,OAAgB;IAChE,OAAO,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,4FAA4F;AAC5F,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB;;;;GAIG;AACH,SAAS,UAAU,CAAC,GAAW;IAC9B,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,OAAO,CAC9C,8BAA8B,EAC9B,CAAC,KAAK,EAAE,OAA2B,EAAE,EAAE,CAAC,OAAO,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CACvG,CAAC;IACF,OAAO,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC9G,CAAC","sourcesContent":["// The app kit's data directory (slice 13 §4, decision \"The app kit, point 4: storage\"): one fixed layout, made private\n// at every start. `server/` holds the server's store and files, `workers/<kind>/<address>/` each worker's store and\n// files, `plugins/` the user's plugins root, `logs/` the logs, `cache/` what only saves time (`workers/<kind>/`, each\n// worker kind's base, written again at every start; `node/`, the workers' compile cache), `owner-token` the owner's token for command-line\n// clients. Directories are 0700 and stores 0600, also when they existed looser before (other local users must not\n// read the sessions in a store, nor replace it).\n\nimport { createHash } from \"node:crypto\";\nimport { chmod, mkdir, open, realpath, stat } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { join, parse } from \"node:path\";\nimport type { Address } from \"../../contracts/index.ts\";\n\n/** The paths of a data directory. */\nexport type AppLayout = {\n\treadonly dataDir: string;\n\treadonly server: string;\n\treadonly serverStore: string;\n\treadonly workers: string;\n\treadonly plugins: string;\n\treadonly logs: string;\n\t/** Each worker kind's base, in `<kind>/` (`WorkersOptions.baseDir`): written again at every start. */\n\treadonly workerBases: string;\n\t/** Node's compile cache for the workers (`NODE_COMPILE_CACHE`). */\n\treadonly compileCache: string;\n\treadonly ownerToken: string;\n\treadonly cookieSecret: string;\n};\n\n/** The data directory of app `name` unless the start script names one: `~/.<name>`. */\nexport function defaultDataDir(name: string): string {\n\treturn join(homedir(), `.${name}`);\n}\n\n/**\n * The real path of the data directory `path`, made when missing (mode 0700), refused when the kit must not make it\n * private: the home directory, a file system's root, or a directory another user owns (a clear error, instead of\n * tightening a directory others use or failing on `EPERM`). Its mode is set on the real path, never through a link.\n */\nexport async function openDataDir(path: string): Promise<string> {\n\tawait mkdir(path, { recursive: true, mode: 0o700 });\n\tconst dataDir = await realpath(path);\n\tconst home = await realpath(homedir());\n\tif (dataDir === home || dataDir === parse(dataDir).root) {\n\t\tconst what = dataDir === home ? \"the home directory\" : \"a file system's root\";\n\t\tthrow new Error(`startServer: the data directory ${dataDir} is ${what}; name a directory of the app's own`);\n\t}\n\tconst { uid } = await stat(dataDir);\n\tif (process.getuid !== undefined && uid !== process.getuid()) {\n\t\tthrow new Error(`startServer: the data directory ${dataDir} belongs to another user (uid ${uid})`);\n\t}\n\treturn dataDir;\n}\n\n/** The layout of `dataDir` (a real path, `openDataDir`'s), its directories made private (`privateDirectory`). */\nexport async function createLayout(dataDir: string): Promise<AppLayout> {\n\tawait privateDirectory(dataDir);\n\tconst layout: AppLayout = {\n\t\tdataDir,\n\t\tserver: join(dataDir, \"server\"),\n\t\tserverStore: join(dataDir, \"server\", \"store.sqlite\"),\n\t\tworkers: join(dataDir, \"workers\"),\n\t\tplugins: join(dataDir, \"plugins\"),\n\t\tlogs: join(dataDir, \"logs\"),\n\t\tworkerBases: join(dataDir, \"cache\", \"workers\"),\n\t\tcompileCache: join(dataDir, \"cache\", \"node\"),\n\t\townerToken: join(dataDir, \"owner-token\"),\n\t\tcookieSecret: join(dataDir, \"server\", \"cookie-secret\"),\n\t};\n\tconst dirs = [layout.server, layout.workers, layout.plugins, layout.logs, join(dataDir, \"cache\")];\n\tfor (const dir of [...dirs, layout.workerBases, layout.compileCache]) await privateDirectory(dir);\n\treturn layout;\n}\n\n/** Makes `dir` (and missing parents) with mode 0700, and sets 0700 on it when it existed. */\nexport async function privateDirectory(dir: string): Promise<void> {\n\tawait mkdir(dir, { recursive: true, mode: 0o700 });\n\tawait chmod(dir, 0o700);\n}\n\n/**\n * Makes the store file `path` private before SQLite opens it: created empty with mode 0600 when missing (SQLite gives\n * its journal files the database's mode), else set to 0600 with the journal files it has.\n */\nexport async function privateStore(path: string): Promise<void> {\n\tawait (await open(path, \"a\", 0o600)).close();\n\tfor (const file of [path, `${path}-wal`, `${path}-shm`]) {\n\t\tawait chmod(file, 0o600).catch((error: NodeJS.ErrnoException) => {\n\t\t\tif (error.code !== \"ENOENT\") throw error;\n\t\t});\n\t}\n}\n\n/** The directory of the worker at `address`: `workers/<kind>/<its key, encoded>`. */\nexport function workerDirectory(dataDir: string, address: Address): string {\n\treturn join(dataDir, \"workers\", address.kind, encodedKey(address.key));\n}\n\n/** The longest key kept readable as a directory name; a longer one is named by its hash. */\nconst READABLE_KEY = 160;\n\n/**\n * An address key as one directory name: percent-encoded (`/`, `\\`, `.` and every other character a file system might\n * treat specially included), or its SHA-256 when that is longer than `READABLE_KEY`. Capital letters are encoded too:\n * on a case-insensitive file system (macOS) `p|A` and `p|a` would otherwise share a directory.\n */\nfunction encodedKey(key: string): string {\n\tconst encoded = encodeURIComponent(key).replace(\n\t\t/(%[0-9A-F]{2})|[.!'()*~A-Z]/g,\n\t\t(match, escaped: string | undefined) => escaped ?? `%${match.charCodeAt(0).toString(16).toUpperCase()}`,\n\t);\n\treturn encoded.length <= READABLE_KEY ? encoded : `sha256-${createHash(\"sha256\").update(key).digest(\"hex\")}`;\n}\n"]}

package/dist/node/app/owner.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from "../../context/index.ts";
+import type { Principal } from "../../data/index.ts";
+import { type Facet, type Host } from "../../host/index.ts";
+/** The owner link's one-time token: made at each start (the previous one dropped), consumed by its first use. */
+export declare class OwnerLink {
+    #private;
+    /** A fresh token (the previous one no longer valid), valid for 10 minutes. */
+    renew(): string;
+    /** Whether `token` is the current one and has not expired; it is used up either way when it matches. */
+    consume(token: string): boolean;
+}
+/** The path of the owner link's page and post. */
+export declare const OWNER_PATH = "/_chord/owner";
+/**
+ * The kit's facet for the owner link: `GET /_chord/owner`, a page posting the fragment's token, and `POST
+ * /_chord/owner`, which consumes it and answers with a session cookie of `owner`.
+ */
+export declare function ownerFacet<P extends Principal>(link: OwnerLink, owner: P): Facet<P>;
+/**
+ * A sign-in page for a link with a token in its fragment (the owner link, an invite): its script (the response's nonce)
+ * posts the token to `path`, then opens the app.
+ */
+export declare function fragmentPage(path: string, nonce: string): string;
+/**
+ * The owner token file at `path`: kept when its token still authenticates as `owner` (its session exists, its secret
+ * matches, it has not expired, it names `owner`; its mode set to 0600 again), else a new device session of `owner`
+ * written there (mode 0600, in one step), the old file's session revoked when it names another principal (the owner
+ * changed). Its token, for the start script.
+ */
+export declare function ownerTokenFile<P extends Principal>(path: string, owner: P, host: Host<P>, context: Context): Promise<string>;
+//# sourceMappingURL=owner.d.ts.map

package/dist/node/app/owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../../src/node/app/owner.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAe,KAAK,KAAK,EAAE,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAQzE,iHAAiH;AACjH,qBAAa,SAAS;;IAIrB,8EAA8E;IAC9E,KAAK,IAAI,MAAM,CAKd;IAED,wGAAwG;IACxG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK9B;CACD;AAED,kDAAkD;AAClD,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAE1C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CA2BnF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAShE;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,SAAS,EACvD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,CAAC,CAkBjB"}

package/dist/node/app/owner.js

@@ -0,0 +1,104 @@
+// The owner (slice 13 §2, decisions "The app kit, point 3: authentication" and "The kit's owner is a principal the app
+// chooses"): the owner is the principal the app names (`principal.owner`); no owner by loopback alone. At each start
+// the kit makes a one-time owner link (a random token, single use, valid 10 minutes, the previous one dropped); the
+// start script prints it. Its page reads the token from the URL's fragment (never sent to a server, so never in a
+// log) and posts it; the post consumes it and sets a browser session cookie for the owner. The owner token file
+// (mode 0600) carries a device session of the owner for command-line clients on the same machine.
+import { chmod } from "node:fs/promises";
+import { samePrincipal } from "../../data/principal.js";
+import { defineFacet } from "../../host/index.js";
+import { Http } from "../http/index.js";
+import { hashToken, matchesHash, newToken, readSecret, writeSecret } from "./secrets.js";
+import { Sessions } from "./sessions.js";
+/** How long an owner link is valid: 10 minutes. */
+const OWNER_LINK_MS = 10 * 60_000;
+/** The owner link's one-time token: made at each start (the previous one dropped), consumed by its first use. */
+export class OwnerLink {
+    #hash;
+    #expires = 0;
+    /** A fresh token (the previous one no longer valid), valid for 10 minutes. */
+    renew() {
+        const token = newToken();
+        this.#hash = hashToken(token);
+        this.#expires = Date.now() + OWNER_LINK_MS;
+        return token;
+    }
+    /** Whether `token` is the current one and has not expired; it is used up either way when it matches. */
+    consume(token) {
+        const hash = this.#hash;
+        if (hash === undefined || !matchesHash(token, hash))
+            return false;
+        this.#hash = undefined;
+        return Date.now() < this.#expires;
+    }
+}
+/** The path of the owner link's page and post. */
+export const OWNER_PATH = "/_chord/owner";
+/**
+ * The kit's facet for the owner link: `GET /_chord/owner`, a page posting the fragment's token, and `POST
+ * /_chord/owner`, which consumes it and answers with a session cookie of `owner`.
+ */
+export function ownerFacet(link, owner) {
+    return defineFacet((_host, self) => self.contribute(Http, {
+        routes: {
+            [`GET ${OWNER_PATH}`]: {
+                public: true,
+                handler: async (request) => ({ kind: "html", body: fragmentPage(OWNER_PATH, request.nonce) }),
+            },
+            [`POST ${OWNER_PATH}`]: {
+                public: true,
+                handler: async (request, ctx) => {
+                    const body = (await request.json());
+                    // A trust boundary: anyone may post here.
+                    if (typeof body?.token !== "string" || !link.consume(body.token))
+                        return { kind: "error", status: 403 };
+                    const sessions = await ctx.get(Sessions, {});
+                    const secure = request.provenance.kind !== "local";
+                    const issued = await sessions.issue({ principal: owner, label: "owner browser", kind: "browser", secure }, ctx);
+                    return { kind: "json", value: "signed in", headers: { "Set-Cookie": issued.cookie } };
+                },
+            },
+        },
+    }));
+}
+/**
+ * A sign-in page for a link with a token in its fragment (the owner link, an invite): its script (the response's nonce)
+ * posts the token to `path`, then opens the app.
+ */
+export function fragmentPage(path, nonce) {
+    return [
+        "<!doctype html><title>Sign in</title><p id=status>Signing in…</p>",
+        `<script nonce="${nonce}">`,
+        "const token = location.hash.slice(1); history.replaceState(null, '', location.pathname);",
+        `fetch(${JSON.stringify(path)}, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token }) })`,
+        "  .then((r) => { if (r.ok) location.replace('/'); else document.getElementById('status').textContent = 'This link is used up or expired.'; });",
+        "</script>",
+    ].join("\n");
+}
+/**
+ * The owner token file at `path`: kept when its token still authenticates as `owner` (its session exists, its secret
+ * matches, it has not expired, it names `owner`; its mode set to 0600 again), else a new device session of `owner`
+ * written there (mode 0600, in one step), the old file's session revoked when it names another principal (the owner
+ * changed). Its token, for the start script.
+ */
+export async function ownerTokenFile(path, owner, host, context) {
+    const existing = await readSecret(path);
+    return host.root(async (ctx) => {
+        const sessions = await ctx.get(Sessions, {});
+        if (existing !== undefined) {
+            // `verify` gives what `issue` stored: a principal of the app's type, or `null`.
+            const verified = (await sessions.verify(existing, ctx));
+            if (samePrincipal(verified ?? undefined, owner, ctx)) {
+                await chmod(path, 0o600);
+                return existing;
+            }
+            // The kit made that session for the file; replacing the file ends it.
+            if (verified !== null)
+                await sessions.revoke(existing.slice(0, existing.indexOf(".")), ctx);
+        }
+        const { token } = await sessions.issue({ principal: owner, label: "owner token file", kind: "device" }, ctx);
+        await writeSecret(path, token, existing === undefined ? "create" : "replace");
+        return token;
+    }, context);
+}
+//# sourceMappingURL=owner.js.map

package/dist/node/app/owner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.js","sourceRoot":"","sources":["../../../src/node/app/owner.ts"],"names":[],"mappings":"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","sourcesContent":["// The owner (slice 13 §2, decisions \"The app kit, point 3: authentication\" and \"The kit's owner is a principal the app\n// chooses\"): the owner is the principal the app names (`principal.owner`); no owner by loopback alone. At each start\n// the kit makes a one-time owner link (a random token, single use, valid 10 minutes, the previous one dropped); the\n// start script prints it. Its page reads the token from the URL's fragment (never sent to a server, so never in a\n// log) and posts it; the post consumes it and sets a browser session cookie for the owner. The owner token file\n// (mode 0600) carries a device session of the owner for command-line clients on the same machine.\n\nimport { chmod } from \"node:fs/promises\";\nimport type { Context } from \"../../context/index.ts\";\nimport type { Principal } from \"../../data/index.ts\";\nimport { samePrincipal } from \"../../data/principal.ts\";\nimport { defineFacet, type Facet, type Host } from \"../../host/index.ts\";\nimport { Http } from \"../http/index.ts\";\nimport { hashToken, matchesHash, newToken, readSecret, writeSecret } from \"./secrets.ts\";\nimport { Sessions } from \"./sessions.ts\";\n\n/** How long an owner link is valid: 10 minutes. */\nconst OWNER_LINK_MS = 10 * 60_000;\n\n/** The owner link's one-time token: made at each start (the previous one dropped), consumed by its first use. */\nexport class OwnerLink {\n\t#hash: string | undefined;\n\t#expires = 0;\n\n\t/** A fresh token (the previous one no longer valid), valid for 10 minutes. */\n\trenew(): string {\n\t\tconst token = newToken();\n\t\tthis.#hash = hashToken(token);\n\t\tthis.#expires = Date.now() + OWNER_LINK_MS;\n\t\treturn token;\n\t}\n\n\t/** Whether `token` is the current one and has not expired; it is used up either way when it matches. */\n\tconsume(token: string): boolean {\n\t\tconst hash = this.#hash;\n\t\tif (hash === undefined || !matchesHash(token, hash)) return false;\n\t\tthis.#hash = undefined;\n\t\treturn Date.now() < this.#expires;\n\t}\n}\n\n/** The path of the owner link's page and post. */\nexport const OWNER_PATH = \"/_chord/owner\";\n\n/**\n * The kit's facet for the owner link: `GET /_chord/owner`, a page posting the fragment's token, and `POST\n * /_chord/owner`, which consumes it and answers with a session cookie of `owner`.\n */\nexport function ownerFacet<P extends Principal>(link: OwnerLink, owner: P): Facet<P> {\n\treturn defineFacet<P>((_host, self) =>\n\t\tself.contribute(Http, {\n\t\t\troutes: {\n\t\t\t\t[`GET ${OWNER_PATH}`]: {\n\t\t\t\t\tpublic: true,\n\t\t\t\t\thandler: async (request) => ({ kind: \"html\", body: fragmentPage(OWNER_PATH, request.nonce) }),\n\t\t\t\t},\n\t\t\t\t[`POST ${OWNER_PATH}`]: {\n\t\t\t\t\tpublic: true,\n\t\t\t\t\thandler: async (request, ctx) => {\n\t\t\t\t\t\tconst body = (await request.json()) as { readonly token?: unknown } | null;\n\t\t\t\t\t\t// A trust boundary: anyone may post here.\n\t\t\t\t\t\tif (typeof body?.token !== \"string\" || !link.consume(body.token))\n\t\t\t\t\t\t\treturn { kind: \"error\", status: 403 };\n\t\t\t\t\t\tconst sessions = await ctx.get(Sessions, {});\n\t\t\t\t\t\tconst secure = request.provenance.kind !== \"local\";\n\t\t\t\t\t\tconst issued = await sessions.issue(\n\t\t\t\t\t\t\t{ principal: owner, label: \"owner browser\", kind: \"browser\", secure },\n\t\t\t\t\t\t\tctx,\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn { kind: \"json\", value: \"signed in\", headers: { \"Set-Cookie\": issued.cookie } };\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t}),\n\t);\n}\n\n/**\n * A sign-in page for a link with a token in its fragment (the owner link, an invite): its script (the response's nonce)\n * posts the token to `path`, then opens the app.\n */\nexport function fragmentPage(path: string, nonce: string): string {\n\treturn [\n\t\t\"<!doctype html><title>Sign in</title><p id=status>Signing in…</p>\",\n\t\t`<script nonce=\"${nonce}\">`,\n\t\t\"const token = location.hash.slice(1); history.replaceState(null, '', location.pathname);\",\n\t\t`fetch(${JSON.stringify(path)}, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token }) })`,\n\t\t\"  .then((r) => { if (r.ok) location.replace('/'); else document.getElementById('status').textContent = 'This link is used up or expired.'; });\",\n\t\t\"</script>\",\n\t].join(\"\\n\");\n}\n\n/**\n * The owner token file at `path`: kept when its token still authenticates as `owner` (its session exists, its secret\n * matches, it has not expired, it names `owner`; its mode set to 0600 again), else a new device session of `owner`\n * written there (mode 0600, in one step), the old file's session revoked when it names another principal (the owner\n * changed). Its token, for the start script.\n */\nexport async function ownerTokenFile<P extends Principal>(\n\tpath: string,\n\towner: P,\n\thost: Host<P>,\n\tcontext: Context,\n): Promise<string> {\n\tconst existing = await readSecret(path);\n\treturn host.root(async (ctx) => {\n\t\tconst sessions = await ctx.get(Sessions, {});\n\t\tif (existing !== undefined) {\n\t\t\t// `verify` gives what `issue` stored: a principal of the app's type, or `null`.\n\t\t\tconst verified = (await sessions.verify(existing, ctx)) as P | null;\n\t\t\tif (samePrincipal(verified ?? undefined, owner, ctx)) {\n\t\t\t\tawait chmod(path, 0o600);\n\t\t\t\treturn existing;\n\t\t\t}\n\t\t\t// The kit made that session for the file; replacing the file ends it.\n\t\t\tif (verified !== null) await sessions.revoke(existing.slice(0, existing.indexOf(\".\")), ctx);\n\t\t}\n\t\tconst { token } = await sessions.issue({ principal: owner, label: \"owner token file\", kind: \"device\" }, ctx);\n\t\tawait writeSecret(path, token, existing === undefined ? \"create\" : \"replace\");\n\t\treturn token;\n\t}, context);\n}\n"]}

package/dist/node/app/pairing.d.ts

@@ -0,0 +1,55 @@
+import type { Principal } from "../../data/index.ts";
+import { type Facet } from "../../host/index.ts";
+/** Who starts a pairing: the signed-in owner (not counted), or an anonymous client at an address (counted). */
+export type PairingStarter = {
+    readonly kind: "owner";
+} | {
+    readonly kind: "anonymous";
+    readonly address: string;
+};
+/** One pairing under way: its code, the device's label, who started it, its expiry, its token once approved. */
+type Pairing = {
+    readonly code: string;
+    readonly label: string;
+    readonly by: PairingStarter;
+    readonly expires: number;
+    token?: string;
+};
+/** The limits of pairings under way: in all (100 by default) and per client address (10 by default). */
+export type PairingLimits = {
+    readonly maxPending?: number;
+    readonly perAddress?: number;
+};
+/** The pairings under way, by code and by their poll secret's hash, with the anonymous ones counted. */
+export declare class Pairings {
+    #private;
+    constructor(limits?: PairingLimits);
+    /**
+     * A new pairing for a device labelled `label`, started `by` the owner or an anonymous client: its code (for the
+     * owner) and its poll secret (for the device); `undefined` when an anonymous client reached a limit.
+     */
+    begin(label: string, by: PairingStarter): {
+        readonly code: string;
+        readonly poll: string;
+    } | undefined;
+    /** The pairing waiting for approval under `code` (any case), unexpired. */
+    waiting(code: string): Pairing | undefined;
+    /** What a poll with `poll` learns: still waiting, the device's token (once: the pairing ends), or nothing. */
+    poll(poll: string): {
+        readonly kind: "waiting";
+    } | {
+        readonly kind: "approved";
+        readonly token: string;
+    } | undefined;
+}
+/** The pairing routes' prefix. */
+export declare const PAIR_PATH = "/_chord/pair";
+/**
+ * The kit's facet for device pairing: `POST /_chord/pair` (public: `{ label? }` → `{ code, poll }`, 429 past a limit
+ * unless the owner asks), `POST /_chord/pair/poll` (public: `{ poll }` → `{ status: "waiting" }`, `{ status:
+ * "approved", token }` once, else 404), `GET` and `POST /_chord/pair/:code` (`owner`'s confirm page and approval: a
+ * device session of `owner`).
+ */
+export declare function pairingFacet<P extends Principal>(pairings: Pairings, owner: P): Facet<P>;
+export {};
+//# sourceMappingURL=pairing.d.ts.map

package/dist/node/app/pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../../src/node/app/pairing.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAW9D,+GAA+G;AAC/G,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnH,gHAAgH;AAChH,KAAK,OAAO,GAAG;IACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wGAAwG;AACxG,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3F,wGAAwG;AACxG,qBAAa,QAAQ;;IAQpB,YAAY,MAAM,GAAE,aAAkB,EAGrC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAgBrG;IAED,2EAA2E;IAC3E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAIzC;IAED,8GAA8G;IAC9G,IAAI,CACH,IAAI,EAAE,MAAM,GACV;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;KAAE,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAQlG;CAqBD;AASD,kCAAkC;AAClC,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAiDxF"}