@earendil-works/chord 1.5.0 → 1.5.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../../src/node/app/sessions.ts"],"names":[],"mappings":"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","sourcesContent":["// Sessions (slice 13 §2, decision \"The app kit, point 3: authentication\"): the kit's object on the server that issues\n// and revokes sessions, and its authenticator. A session is a principal behind a token `<id>.<secret>` (random); only\n// the secret's hash is kept. A browser carries its token in the kit's signed session cookie (`HttpOnly`,\n// `SameSite=Strict`), a command-line client in `Authorization: Bearer <token>`. Browser and device sessions persist in\n// the server's store and expire after 400 days unused; ephemeral sessions (a pick-a-name login, a public route) live\n// in memory only (`EphemeralSessions`), at most `maxEphemeral` of them (past it the oldest ends), so a public login\n// costs the same whatever came before; each ends with its client's connection (its last link closed, a grace period\n// passed: the links endpoint's `opened` hook counts them), and none outlives the server's run.\n\nimport type { Context } from \"../../context/index.ts\";\nimport { arr, bool, local, map, method, num, obj, oneOf, opt, str, unknown } from \"../../contracts/index.ts\";\nimport type { Principal } from \"../../data/index.ts\";\nimport { defineState } from \"../../documents/index.ts\";\nimport { defineFacet, type Facet } from \"../../host/index.ts\";\nimport type { JsonValue } from \"../../json.ts\";\nimport {\n\tAuthenticators,\n\tcookie,\n\tHttp,\n\ttype HttpRequest,\n\ttype HttpWrap,\n\ttype Provenance,\n\treadCookie,\n\treadSignedCookie,\n} from \"../http/index.ts\";\nimport { EphemeralSessions } from \"./ephemeral-sessions.ts\";\nimport { hashToken, matchesHash, newToken } from \"./secrets.ts\";\n\n/** What a session is for: a browser (its cookie), a device (a command-line client's token), an ephemeral login. */\nexport type SessionKind = \"browser\" | \"device\" | \"ephemeral\";\n\n/** A browser or device session as `Sessions.list` shows it: never its token or hash. */\nexport type SessionInfo = {\n\treadonly id: string;\n\treadonly label: string;\n\treadonly kind: \"browser\" | \"device\";\n\treadonly principal: unknown;\n\treadonly created: number;\n\treadonly lastUsed: number;\n};\n\n/** The kit's sessions (one per server): issue, verify, revoke, and the watchable list of persisted ones. */\nexport const Sessions = local(\"chord.app.sessions\", {\n\tversion: 1,\n\tparams: {},\n\tmembers: {\n\t\t/** The browser and device sessions (ephemeral ones are not listed: there may be many, and they are short). */\n\t\tlist: arr(\n\t\t\tobj({\n\t\t\t\tid: str(),\n\t\t\t\tlabel: str(),\n\t\t\t\tkind: oneOf(\"browser\", \"device\"),\n\t\t\t\tprincipal: unknown(),\n\t\t\t\tcreated: num(),\n\t\t\t\tlastUsed: num(),\n\t\t\t}),\n\t\t),\n\t\t/**\n\t\t * A new session for `principal`: its id, its token (shown once, kept only hashed) and the session cookie carrying\n\t\t * it for a browser (`Set-Cookie`; `secure` for a remote one).\n\t\t */\n\t\tissue: method(\n\t\t\tobj({\n\t\t\t\tprincipal: unknown(),\n\t\t\t\tlabel: str(),\n\t\t\t\tkind: oneOf(\"browser\", \"device\", \"ephemeral\"),\n\t\t\t\tsecure: opt(bool()),\n\t\t\t}),\n\t\t\tobj({ id: str(), token: str(), cookie: str() }),\n\t\t),\n\t\t/** The principal `token` authenticates as, or `null` (unknown, revoked, expired, malformed). */\n\t\tverify: method(str(), unknown()),\n\t\t/** Ends session `id` at once: its token authenticates nothing more. */\n\t\trevoke: method(str()),\n\t},\n});\n\n/** The name of the kit's session cookie. */\nexport const SESSION_COOKIE = \"chord-session\";\n\n/** The stored sessions: by id, each with its secret's hash and its principal (as JSON text: any of the app's). */\nconst SessionsDocument = defineState(\"chord.app.sessions\", {\n\tschema: obj({\n\t\tsessions: map(\n\t\t\tobj({\n\t\t\t\thash: str(),\n\t\t\t\tlabel: str(),\n\t\t\t\tkind: oneOf(\"browser\", \"device\"),\n\t\t\t\tprincipal: str(),\n\t\t\t\tcreated: num(),\n\t\t\t\tlastUsed: num(),\n\t\t\t}),\n\t\t),\n\t}),\n\tversion: 1,\n\tinitial: () => ({ sessions: {} }),\n\tpersist: true,\n\tcheckpointWhen: (_value, _ops, { deltasSinceBase }) => deltasSinceBase >= 50,\n});\n\n/** How often a session's `lastUsed` is written at most: once a minute (not one commit per request). */\nconst TOUCH_MS = 60_000;\n\n/** How long a persisted session lives unused: 400 days, as its cookie. */\nconst SESSION_IDLE_MS = 400 * 24 * 60 * 60_000;\n\n/** The sessions' limits: how many ephemeral sessions live at once (1,000 by default; past it the oldest ends). */\nexport type SessionLimits = { readonly maxEphemeral?: number };\n\n/** The kit's sessions: the facet for the server's core facets, and the links endpoint's `opened` hook. */\nexport type KitSessions<P extends Principal> = {\n\treadonly facet: Facet<P>;\n\t/** A link opened with `request`'s credentials: an ephemeral session's links are counted (it ends with its last). */\n\treadonly opened: (request: HttpRequest) => (() => void) | undefined;\n};\n\n/**\n * The kit's sessions: its facet serving `Sessions` (a host-lifetime object) and contributing its authenticator (the\n * bearer token first, else the session cookie signed with `cookieSecret`), and the links hook ending an ephemeral\n * session with its client's connection.\n */\nexport function createSessions<P extends Principal>(cookieSecret: string, limits: SessionLimits = {}): KitSessions<P> {\n\tconst ephemeral = new EphemeralSessions(limits.maxEphemeral ?? 1000);\n\tconst opened = (request: HttpRequest): (() => void) | undefined => {\n\t\tconst token = bearerToken(request) ?? readCookie(request, SESSION_COOKIE, cookieSecret);\n\t\tconst dot = token?.indexOf(\".\") ?? -1;\n\t\treturn dot > 0 ? ephemeral.linkOpened(token!.slice(0, dot)) : undefined;\n\t};\n\treturn { facet: sessionsFacet<P>(cookieSecret, ephemeral), opened };\n}\n\n/** The facet of `createSessions`. */\nfunction sessionsFacet<P extends Principal>(cookieSecret: string, ephemeral: EphemeralSessions): Facet<P> {\n\treturn defineFacet<P>((host) =>\n\t\thost.serve(Sessions, (_params, self) => {\n\t\t\tconst document = self.state(SessionsDocument);\n\t\t\tconst change = (fn: (sessions: Record<string, { lastUsed: number }>) => void, context: Context) =>\n\t\t\t\t// Not awaited by authentication: the request goes on; a write that fails is made again by a later request.\n\t\t\t\tvoid document.change((draft) => fn(draft.sessions), context).catch(() => {});\n\t\t\t/** The principal of `token`, or `undefined`; touches or lazily removes the persisted session it names. */\n\t\t\tconst authenticate = (token: string, context: Context): Principal | undefined => {\n\t\t\t\tconst dot = token.indexOf(\".\");\n\t\t\t\tif (dot <= 0) return undefined;\n\t\t\t\tconst id = token.slice(0, dot);\n\t\t\t\tconst secret = token.slice(dot + 1);\n\t\t\t\tconst short = ephemeral.get(id);\n\t\t\t\tif (short !== undefined) return matchesHash(secret, short.hash) ? short.principal : undefined;\n\t\t\t\t// A trust boundary: `id` is the client's (`Object.hasOwn`: no inherited member is a session).\n\t\t\t\tconst sessions = document.value.sessions;\n\t\t\t\tif (!Object.hasOwn(sessions, id)) return undefined;\n\t\t\t\tconst session = sessions[id]!;\n\t\t\t\tif (!matchesHash(secret, session.hash)) return undefined;\n\t\t\t\tconst now = Date.now();\n\t\t\t\tif (now - session.lastUsed > SESSION_IDLE_MS) {\n\t\t\t\t\tchange((draft) => {\n\t\t\t\t\t\tdelete draft[id];\n\t\t\t\t\t}, context);\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\t\t\t\tif (now - session.lastUsed > TOUCH_MS) {\n\t\t\t\t\tchange((draft) => {\n\t\t\t\t\t\tif (Object.hasOwn(draft, id)) draft[id]!.lastUsed = now;\n\t\t\t\t\t}, context);\n\t\t\t\t}\n\t\t\t\t// Stored by `issue` from a principal of the app's type.\n\t\t\t\treturn JSON.parse(session.principal) as Principal;\n\t\t\t};\n\t\t\tself.contribute(Authenticators, (request, context) => {\n\t\t\t\tconst token = bearerToken(request) ?? readCookie(request, SESSION_COOKIE, cookieSecret);\n\t\t\t\treturn token === undefined ? undefined : authenticate(token, context);\n\t\t\t});\n\t\t\tself.contribute(Http, { wraps: [rollingCookie(cookieSecret, authenticate)] });\n\t\t\treturn {\n\t\t\t\tlist: self.derive([document], ([value]) =>\n\t\t\t\t\tObject.entries(value.sessions).map(([id, { label, kind, principal, created, lastUsed }]) => ({\n\t\t\t\t\t\tid,\n\t\t\t\t\t\tlabel,\n\t\t\t\t\t\tkind,\n\t\t\t\t\t\t// Stored by `issue` as JSON text.\n\t\t\t\t\t\tprincipal: JSON.parse(principal) as JsonValue,\n\t\t\t\t\t\tcreated,\n\t\t\t\t\t\tlastUsed,\n\t\t\t\t\t})),\n\t\t\t\t),\n\t\t\t\tissue: async ({ principal, label, kind, secure }, ctx) => {\n\t\t\t\t\tconst id = newToken(12);\n\t\t\t\t\tconst secret = newToken(32);\n\t\t\t\t\tif (kind === \"ephemeral\") {\n\t\t\t\t\t\t// Principals are the app's: `issue`'s callers pass one of its type.\n\t\t\t\t\t\tephemeral.issue(id, hashToken(secret), principal as Principal);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tconst now = Date.now();\n\t\t\t\t\t\tconst stored = JSON.stringify(principal);\n\t\t\t\t\t\tawait document.change((draft) => {\n\t\t\t\t\t\t\tdraft.sessions[id] = {\n\t\t\t\t\t\t\t\thash: hashToken(secret),\n\t\t\t\t\t\t\t\tlabel,\n\t\t\t\t\t\t\t\tkind,\n\t\t\t\t\t\t\t\tprincipal: stored,\n\t\t\t\t\t\t\t\tcreated: now,\n\t\t\t\t\t\t\t\tlastUsed: now,\n\t\t\t\t\t\t\t};\n\t\t\t\t\t\t}, ctx);\n\t\t\t\t\t}\n\t\t\t\t\tconst token = `${id}.${secret}`;\n\t\t\t\t\t// Only whether the browser is remote matters to the cookie (`Secure`).\n\t\t\t\t\tconst provenance: Provenance = secure === true ? { kind: \"remote\", host: \"\" } : { kind: \"local\" };\n\t\t\t\t\tconst set = sessionCookie(token, kind, { provenance }, cookieSecret);\n\t\t\t\t\treturn { id, token, cookie: set };\n\t\t\t\t},\n\t\t\t\tverify: async (token, ctx) => (authenticate(token, ctx) as JsonValue | undefined) ?? null,\n\t\t\t\trevoke: async (id, ctx) => {\n\t\t\t\t\tif (ephemeral.revoke(id)) return null;\n\t\t\t\t\tawait document.change((draft) => {\n\t\t\t\t\t\tdelete draft.sessions[id];\n\t\t\t\t\t}, ctx);\n\t\t\t\t\treturn null;\n\t\t\t\t},\n\t\t\t};\n\t\t}),\n\t);\n}\n\n/**\n * The session cookie carrying `token` (a session of `kind`) for a browser of `request`'s provenance: a persisted\n * session's lives as long as the session does unused (400 days, renewed by `rollingCookie`), an ephemeral one's only\n * while the browser runs.\n */\nfunction sessionCookie(\n\ttoken: string,\n\tkind: SessionKind,\n\trequest: Pick<HttpRequest, \"provenance\">,\n\tsecret: string,\n): string {\n\tconst maxAge = kind === \"ephemeral\" ? undefined : SESSION_IDLE_MS / 1000;\n\treturn cookie(SESSION_COOKIE, token, { secret, request, maxAge });\n}\n\n/** How old a session cookie gets before a response renews it: a day. */\nconst ROLL_MS = 24 * 60 * 60_000;\n\n/**\n * The wrap around every route renewing the session cookie a request signed in with once it is older than a day: the\n * response sets it again with a fresh signed expiry, so a browser used within every 400 days stays signed in. Not when\n * the route sets a cookie itself, nor for an ephemeral session's (it has no expiry) or a token that no longer\n * authenticates.\n */\nfunction rollingCookie(\n\tsecret: string,\n\tauthenticate: (token: string, context: Context) => Principal | undefined,\n): HttpWrap {\n\treturn {\n\t\tname: \"chord.app.rolling-cookie\",\n\t\tphase: \"headers\",\n\t\tscope: \"all\",\n\t\twrap: async (request, next, ctx) => {\n\t\t\tconst response = await next(request);\n\t\t\tif (ctx.principal === undefined || Object.keys(response.headers ?? {}).some(isSetCookie)) return response;\n\t\t\tconst signed = readSignedCookie(request, SESSION_COOKIE, secret);\n\t\t\tif (signed?.expires === undefined || signed.expires - Date.now() > SESSION_IDLE_MS - ROLL_MS) return response;\n\t\t\tif (authenticate(signed.value, ctx) === undefined) return response;\n\t\t\tconst renewed = sessionCookie(signed.value, \"browser\", request, secret);\n\t\t\treturn { ...response, headers: { ...response.headers, \"Set-Cookie\": renewed } };\n\t\t},\n\t};\n}\n\n/** Whether a header name is `Set-Cookie` (any case). */\nfunction isSetCookie(name: string): boolean {\n\treturn name.toLowerCase() === \"set-cookie\";\n}\n\n/** The token of an `Authorization: Bearer <token>` header. */\nfunction bearerToken(request: HttpRequest): string | undefined {\n\tconst header = request.headers.get(\"authorization\");\n\tconst match = header === null ? null : /^Bearer\\s+(\\S+)$/i.exec(header);\n\treturn match?.[1];\n}\n"]}

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

@@ -0,0 +1,24 @@
+/** One entry to write: its path (`/`-separated, relative) and its bytes, as a size and the chunks that make it up. */
+export type TarEntry = {
+    readonly path: string;
+    readonly size: number;
+    readonly data: AsyncIterable<Uint8Array>;
+};
+/** One entry read: a regular file (its data, to be consumed before the next entry) or a directory. */
+export type TarRead = {
+    readonly kind: "file";
+    readonly path: string;
+    readonly size: number;
+    readonly data: AsyncIterable<Uint8Array>;
+} | {
+    readonly kind: "directory";
+    readonly path: string;
+};
+/** The archive of `entries`, as the chunks of its bytes (two zero blocks end it). */
+export declare function writeTar(entries: AsyncIterable<TarEntry> | Iterable<TarEntry>): AsyncGenerator<Uint8Array>;
+/**
+ * Reads the archive `source` entry by entry (each file's data read fully before the next entry is asked for), refusing
+ * what it may not hold (see the file's header).
+ */
+export declare function readTar(source: AsyncIterable<Uint8Array>): AsyncGenerator<TarRead>;
+//# sourceMappingURL=tar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tar.d.ts","sourceRoot":"","sources":["../../../src/node/app/tar.ts"],"names":[],"mappings":"AAKA,sHAAsH;AACtH,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;CAAE,CAAC;AAElH,sGAAsG;AACtG,MAAM,MAAM,OAAO,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;CAAE,GACjH;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAKzD,qFAAqF;AACrF,wBAAuB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAcjH;AAuDD;;;GAGG;AACH,wBAAuB,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CA0BzF"}

package/dist/node/app/tar.js

@@ -0,0 +1,167 @@
+// A minimal ustar (POSIX tar) writer and reader for the kit's address archives (slice 13 §4): regular files and
+// directories, paths of at most 255 bytes, nothing else. The reader is a trust boundary: an archive may come from
+// anywhere, so it refuses every entry that is no regular file or directory, a path that is absolute, holds `..`, a
+// backslash or NUL, or names an empty segment, and a header whose checksum does not hold.
+/** A tar block. */
+const BLOCK = 512;
+/** The archive of `entries`, as the chunks of its bytes (two zero blocks end it). */
+export async function* writeTar(entries) {
+    for await (const entry of entries) {
+        yield header(entry.path, entry.size);
+        let written = 0;
+        for await (const chunk of entry.data) {
+            written += chunk.length;
+            if (written > entry.size)
+                throw new Error(`tar: ${entry.path} is larger than its size ${entry.size}`);
+            yield chunk;
+        }
+        if (written !== entry.size)
+            throw new Error(`tar: ${entry.path} is ${written} bytes, not ${entry.size}`);
+        const pad = (BLOCK - (entry.size % BLOCK)) % BLOCK;
+        if (pad > 0)
+            yield new Uint8Array(pad);
+    }
+    yield new Uint8Array(BLOCK * 2);
+}
+/** The ustar header of a regular file at `path` of `size` bytes. */
+function header(path, size) {
+    checkPath(path);
+    const block = new Uint8Array(BLOCK);
+    const bytes = new TextEncoder().encode(path);
+    let name = bytes;
+    let prefix = new Uint8Array();
+    if (bytes.length > 100) {
+        // Split at a `/` so the name has at most 100 bytes and the prefix at most 155.
+        const at = path.lastIndexOf("/", path.length - 1);
+        const split = new TextEncoder().encode(path.slice(0, at)).length;
+        if (at < 0 || split > 155 || bytes.length - split - 1 > 100)
+            throw new Error(`tar: the path ${path} is too long`);
+        prefix = bytes.subarray(0, split);
+        name = bytes.subarray(split + 1);
+    }
+    block.set(name, 0);
+    field(block, 100, 8, "0000644");
+    field(block, 108, 8, "0000000");
+    field(block, 116, 8, "0000000");
+    field(block, 124, 12, size.toString(8).padStart(11, "0"));
+    field(block, 136, 12, Math.floor(Date.now() / 1000)
+        .toString(8)
+        .padStart(11, "0"));
+    block.fill(0x20, 148, 156);
+    block[156] = 0x30;
+    block.set(new TextEncoder().encode("ustar\u000000"), 257);
+    block.set(prefix, 345);
+    const sum = block.reduce((total, byte) => total + byte, 0);
+    field(block, 148, 8, `${sum.toString(8).padStart(6, "0")}\u0000 `);
+    return block;
+}
+/** Writes `text` (ASCII) at `offset` of `block`, NUL-terminated within `length`. */
+function field(block, offset, length, text) {
+    const bytes = new TextEncoder().encode(text);
+    if (bytes.length > length)
+        throw new Error(`tar: ${text} does not fit ${length} bytes`);
+    block.set(bytes, offset);
+}
+/** Refuses a path an archive may not hold: absolute, with `..`, `.`, an empty segment, a backslash or a NUL. */
+function checkPath(path) {
+    const segments = path.split("/");
+    const bad = path === "" || path.includes("\\") || path.includes("\u0000") || path.startsWith("/");
+    if (bad || segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new Error(`tar: the path ${JSON.stringify(path)} is refused`);
+    }
+}
+/**
+ * Reads the archive `source` entry by entry (each file's data read fully before the next entry is asked for), refusing
+ * what it may not hold (see the file's header).
+ */
+export async function* readTar(source) {
+    const reader = new ByteReader(source);
+    for (;;) {
+        const block = await reader.read(BLOCK);
+        if (block.length < BLOCK)
+            throw new Error("tar: the archive ends inside a header");
+        if (block.every((byte) => byte === 0))
+            return;
+        const { path, size, type } = parseHeader(block);
+        const padded = Math.ceil(size / BLOCK) * BLOCK;
+        if (type === "directory") {
+            yield { kind: "directory", path };
+            await reader.skip(padded);
+            continue;
+        }
+        let left = size;
+        const data = (async function* () {
+            while (left > 0) {
+                const chunk = await reader.read(Math.min(left, 64 * 1024));
+                if (chunk.length === 0)
+                    throw new Error(`tar: the archive ends inside ${path}`);
+                left -= chunk.length;
+                yield chunk;
+            }
+        })();
+        yield { kind: "file", path, size, data };
+        // What the consumer left unread (also when it ended the data's iteration early), then the padding.
+        await reader.skip(left + padded - size);
+    }
+}
+/** A header's path, size and type, its checksum checked; anything but a regular file or a directory refused. */
+function parseHeader(block) {
+    const stored = Number.parseInt(text(block, 148, 8).trim(), 8);
+    let sum = 0;
+    for (let index = 0; index < BLOCK; index++)
+        sum += index >= 148 && index < 156 ? 0x20 : block[index];
+    if (stored !== sum)
+        throw new Error("tar: a header's checksum does not hold");
+    const flag = String.fromCharCode(block[156]);
+    const type = flag === "0" || flag === "\u0000" ? "file" : flag === "5" ? "directory" : undefined;
+    if (type === undefined)
+        throw new Error(`tar: an entry of type ${JSON.stringify(flag)} is refused (files only)`);
+    const prefix = text(block, 345, 155);
+    const name = text(block, 0, 100);
+    const path = (prefix === "" ? name : `${prefix}/${name}`).replace(/\/$/, "");
+    checkPath(path);
+    const size = Number.parseInt(text(block, 124, 12).trim() || "0", 8);
+    if (!Number.isSafeInteger(size) || size < 0)
+        throw new Error(`tar: ${path} has no valid size`);
+    return { path, size: type === "directory" ? 0 : size, type };
+}
+/** The NUL-terminated text of a header field. */
+function text(block, offset, length) {
+    const bytes = block.subarray(offset, offset + length);
+    const end = bytes.indexOf(0);
+    return new TextDecoder().decode(end < 0 ? bytes : bytes.subarray(0, end));
+}
+/** Reads exactly as many bytes as asked from a stream of chunks (fewer only at its end). */
+class ByteReader {
+    #source;
+    #buffer = new Uint8Array();
+    constructor(source) {
+        this.#source = source[Symbol.asyncIterator]();
+    }
+    /** Up to `length` bytes: `length` unless the stream ends first. */
+    async read(length) {
+        while (this.#buffer.length < length) {
+            const next = await this.#source.next();
+            if (next.done === true)
+                break;
+            const joined = new Uint8Array(this.#buffer.length + next.value.length);
+            joined.set(this.#buffer);
+            joined.set(next.value, this.#buffer.length);
+            this.#buffer = joined;
+        }
+        const taken = this.#buffer.subarray(0, Math.min(length, this.#buffer.length));
+        this.#buffer = this.#buffer.subarray(taken.length);
+        return taken;
+    }
+    /** Skips `length` bytes. */
+    async skip(length) {
+        let left = length;
+        while (left > 0) {
+            const skipped = await this.read(Math.min(left, 64 * 1024));
+            if (skipped.length === 0)
+                throw new Error("tar: the archive ends early");
+            left -= skipped.length;
+        }
+    }
+}
+//# sourceMappingURL=tar.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tar.js","sourceRoot":"","sources":["../../../src/node/app/tar.ts"],"names":[],"mappings":"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","sourcesContent":["// A minimal ustar (POSIX tar) writer and reader for the kit's address archives (slice 13 §4): regular files and\n// directories, paths of at most 255 bytes, nothing else. The reader is a trust boundary: an archive may come from\n// anywhere, so it refuses every entry that is no regular file or directory, a path that is absolute, holds `..`, a\n// backslash or NUL, or names an empty segment, and a header whose checksum does not hold.\n\n/** One entry to write: its path (`/`-separated, relative) and its bytes, as a size and the chunks that make it up. */\nexport type TarEntry = { readonly path: string; readonly size: number; readonly data: AsyncIterable<Uint8Array> };\n\n/** One entry read: a regular file (its data, to be consumed before the next entry) or a directory. */\nexport type TarRead =\n\t| { readonly kind: \"file\"; readonly path: string; readonly size: number; readonly data: AsyncIterable<Uint8Array> }\n\t| { readonly kind: \"directory\"; readonly path: string };\n\n/** A tar block. */\nconst BLOCK = 512;\n\n/** The archive of `entries`, as the chunks of its bytes (two zero blocks end it). */\nexport async function* writeTar(entries: AsyncIterable<TarEntry> | Iterable<TarEntry>): AsyncGenerator<Uint8Array> {\n\tfor await (const entry of entries) {\n\t\tyield header(entry.path, entry.size);\n\t\tlet written = 0;\n\t\tfor await (const chunk of entry.data) {\n\t\t\twritten += chunk.length;\n\t\t\tif (written > entry.size) throw new Error(`tar: ${entry.path} is larger than its size ${entry.size}`);\n\t\t\tyield chunk;\n\t\t}\n\t\tif (written !== entry.size) throw new Error(`tar: ${entry.path} is ${written} bytes, not ${entry.size}`);\n\t\tconst pad = (BLOCK - (entry.size % BLOCK)) % BLOCK;\n\t\tif (pad > 0) yield new Uint8Array(pad);\n\t}\n\tyield new Uint8Array(BLOCK * 2);\n}\n\n/** The ustar header of a regular file at `path` of `size` bytes. */\nfunction header(path: string, size: number): Uint8Array {\n\tcheckPath(path);\n\tconst block = new Uint8Array(BLOCK);\n\tconst bytes = new TextEncoder().encode(path);\n\tlet name = bytes;\n\tlet prefix = new Uint8Array();\n\tif (bytes.length > 100) {\n\t\t// Split at a `/` so the name has at most 100 bytes and the prefix at most 155.\n\t\tconst at = path.lastIndexOf(\"/\", path.length - 1);\n\t\tconst split = new TextEncoder().encode(path.slice(0, at)).length;\n\t\tif (at < 0 || split > 155 || bytes.length - split - 1 > 100) throw new Error(`tar: the path ${path} is too long`);\n\t\tprefix = bytes.subarray(0, split);\n\t\tname = bytes.subarray(split + 1);\n\t}\n\tblock.set(name, 0);\n\tfield(block, 100, 8, \"0000644\");\n\tfield(block, 108, 8, \"0000000\");\n\tfield(block, 116, 8, \"0000000\");\n\tfield(block, 124, 12, size.toString(8).padStart(11, \"0\"));\n\tfield(\n\t\tblock,\n\t\t136,\n\t\t12,\n\t\tMath.floor(Date.now() / 1000)\n\t\t\t.toString(8)\n\t\t\t.padStart(11, \"0\"),\n\t);\n\tblock.fill(0x20, 148, 156);\n\tblock[156] = 0x30;\n\tblock.set(new TextEncoder().encode(\"ustar\\u000000\"), 257);\n\tblock.set(prefix, 345);\n\tconst sum = block.reduce((total, byte) => total + byte, 0);\n\tfield(block, 148, 8, `${sum.toString(8).padStart(6, \"0\")}\\u0000 `);\n\treturn block;\n}\n\n/** Writes `text` (ASCII) at `offset` of `block`, NUL-terminated within `length`. */\nfunction field(block: Uint8Array, offset: number, length: number, text: string): void {\n\tconst bytes = new TextEncoder().encode(text);\n\tif (bytes.length > length) throw new Error(`tar: ${text} does not fit ${length} bytes`);\n\tblock.set(bytes, offset);\n}\n\n/** Refuses a path an archive may not hold: absolute, with `..`, `.`, an empty segment, a backslash or a NUL. */\nfunction checkPath(path: string): void {\n\tconst segments = path.split(\"/\");\n\tconst bad = path === \"\" || path.includes(\"\\\\\") || path.includes(\"\\u0000\") || path.startsWith(\"/\");\n\tif (bad || segments.some((segment) => segment === \"\" || segment === \".\" || segment === \"..\")) {\n\t\tthrow new Error(`tar: the path ${JSON.stringify(path)} is refused`);\n\t}\n}\n\n/**\n * Reads the archive `source` entry by entry (each file's data read fully before the next entry is asked for), refusing\n * what it may not hold (see the file's header).\n */\nexport async function* readTar(source: AsyncIterable<Uint8Array>): AsyncGenerator<TarRead> {\n\tconst reader = new ByteReader(source);\n\tfor (;;) {\n\t\tconst block = await reader.read(BLOCK);\n\t\tif (block.length < BLOCK) throw new Error(\"tar: the archive ends inside a header\");\n\t\tif (block.every((byte) => byte === 0)) return;\n\t\tconst { path, size, type } = parseHeader(block);\n\t\tconst padded = Math.ceil(size / BLOCK) * BLOCK;\n\t\tif (type === \"directory\") {\n\t\t\tyield { kind: \"directory\", path };\n\t\t\tawait reader.skip(padded);\n\t\t\tcontinue;\n\t\t}\n\t\tlet left = size;\n\t\tconst data = (async function* () {\n\t\t\twhile (left > 0) {\n\t\t\t\tconst chunk = await reader.read(Math.min(left, 64 * 1024));\n\t\t\t\tif (chunk.length === 0) throw new Error(`tar: the archive ends inside ${path}`);\n\t\t\t\tleft -= chunk.length;\n\t\t\t\tyield chunk;\n\t\t\t}\n\t\t})();\n\t\tyield { kind: \"file\", path, size, data };\n\t\t// What the consumer left unread (also when it ended the data's iteration early), then the padding.\n\t\tawait reader.skip(left + padded - size);\n\t}\n}\n\n/** A header's path, size and type, its checksum checked; anything but a regular file or a directory refused. */\nfunction parseHeader(block: Uint8Array): {\n\treadonly path: string;\n\treadonly size: number;\n\treadonly type: \"file\" | \"directory\";\n} {\n\tconst stored = Number.parseInt(text(block, 148, 8).trim(), 8);\n\tlet sum = 0;\n\tfor (let index = 0; index < BLOCK; index++) sum += index >= 148 && index < 156 ? 0x20 : block[index]!;\n\tif (stored !== sum) throw new Error(\"tar: a header's checksum does not hold\");\n\tconst flag = String.fromCharCode(block[156]!);\n\tconst type = flag === \"0\" || flag === \"\\u0000\" ? \"file\" : flag === \"5\" ? \"directory\" : undefined;\n\tif (type === undefined) throw new Error(`tar: an entry of type ${JSON.stringify(flag)} is refused (files only)`);\n\tconst prefix = text(block, 345, 155);\n\tconst name = text(block, 0, 100);\n\tconst path = (prefix === \"\" ? name : `${prefix}/${name}`).replace(/\\/$/, \"\");\n\tcheckPath(path);\n\tconst size = Number.parseInt(text(block, 124, 12).trim() || \"0\", 8);\n\tif (!Number.isSafeInteger(size) || size < 0) throw new Error(`tar: ${path} has no valid size`);\n\treturn { path, size: type === \"directory\" ? 0 : size, type };\n}\n\n/** The NUL-terminated text of a header field. */\nfunction text(block: Uint8Array, offset: number, length: number): string {\n\tconst bytes = block.subarray(offset, offset + length);\n\tconst end = bytes.indexOf(0);\n\treturn new TextDecoder().decode(end < 0 ? bytes : bytes.subarray(0, end));\n}\n\n/** Reads exactly as many bytes as asked from a stream of chunks (fewer only at its end). */\nclass ByteReader {\n\treadonly #source: AsyncIterator<Uint8Array>;\n\t#buffer = new Uint8Array();\n\n\tconstructor(source: AsyncIterable<Uint8Array>) {\n\t\tthis.#source = source[Symbol.asyncIterator]();\n\t}\n\n\t/** Up to `length` bytes: `length` unless the stream ends first. */\n\tasync read(length: number): Promise<Uint8Array> {\n\t\twhile (this.#buffer.length < length) {\n\t\t\tconst next = await this.#source.next();\n\t\t\tif (next.done === true) break;\n\t\t\tconst joined = new Uint8Array(this.#buffer.length + next.value.length);\n\t\t\tjoined.set(this.#buffer);\n\t\t\tjoined.set(next.value, this.#buffer.length);\n\t\t\tthis.#buffer = joined;\n\t\t}\n\t\tconst taken = this.#buffer.subarray(0, Math.min(length, this.#buffer.length));\n\t\tthis.#buffer = this.#buffer.subarray(taken.length);\n\t\treturn taken;\n\t}\n\n\t/** Skips `length` bytes. */\n\tasync skip(length: number): Promise<void> {\n\t\tlet left = length;\n\t\twhile (left > 0) {\n\t\t\tconst skipped = await this.read(Math.min(left, 64 * 1024));\n\t\t\tif (skipped.length === 0) throw new Error(\"tar: the archive ends early\");\n\t\t\tleft -= skipped.length;\n\t\t}\n\t}\n}\n"]}

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

@@ -0,0 +1,37 @@
+/** A finished upload: what it was begun with and its size, its bytes moved to the path `finish` was given. */
+export type Finished<T> = {
+    readonly data: T;
+    readonly size: number;
+};
+/**
+ * The uploads under way of one `Files` object, in the directory `run` (this object's own, made on first use), at most
+ * `max` at once: each holds a file handle until it ends, so a caller beginning uploads without end would exhaust the
+ * process's descriptors. Each carries its owner's `T` (what the file becomes when it finishes).
+ */
+export declare class Uploads<T> {
+    #private;
+    constructor(run: string, max: number);
+    /** The bytes accepted by every upload under way (they count against the host's cap). */
+    get size(): number;
+    /** The id of the upload under way whose data `matches`, if any. */
+    find(matches: (data: T) => boolean): string | undefined;
+    /** A new upload carrying `data`: its id; `unavailable` (`busy`) while `max` are under way. */
+    begin(data: T): Promise<string>;
+    /**
+     * Writes `bytes` at `offset` of upload `id`, which must be where the accepted appends reached (else `invalid`, its
+     * details the expected `{ offset }`); `room(adding, fileSize)` refuses what the caps do not allow, before anything
+     * is accepted. A failed write ends the upload.
+     */
+    append(id: string, offset: number, bytes: Uint8Array, room: (adding: number, fileSize: number) => void): Promise<void>;
+    /** The bytes of upload `id` written so far, once its writes in flight landed: where a writer resumes. */
+    uploaded(id: string): Promise<number>;
+    /** Ends upload `id` once its writes landed and moves its file to `path`; refused when a write of it failed. */
+    finish(id: string, path: string): Promise<Finished<T>>;
+    /** Drops upload `id` once its writes landed (an unknown one: nothing): its writer gave up. */
+    cancel(id: string): Promise<void>;
+    /** Drops the uploads unwritten for `idleMs`, once their writes landed. */
+    expire(idleMs: number): Promise<void>;
+    /** Drops every upload under way (their object ended). */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=uploads.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../../../src/node/app/uploads.ts"],"names":[],"mappings":"AAwBA,8GAA8G;AAC9G,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE;;;;GAIG;AACH,qBAAa,OAAO,CAAC,CAAC;;IAKrB,YAAY,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAGnC;IAED,wFAAwF;IACxF,IAAI,IAAI,IAAI,MAAM,CAIjB;IAED,mEAAmE;IACnE,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,MAAM,GAAG,SAAS,CAGtD;IAED,8FAA8F;IACxF,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBpC;IAED;;;;OAIG;IACG,MAAM,CACX,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAC9C,OAAO,CAAC,IAAI,CAAC,CA2Bf;IAED,yGAAyG;IACnG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK1C;IAED,+GAA+G;IACzG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAQ3D;IAED,8FAA8F;IACxF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtC;IAED,0EAA0E;IACpE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK1C;IAED,yDAAyD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;CAqBD"}

package/dist/node/app/uploads.js

@@ -0,0 +1,157 @@
+// Chunked uploads of one `Files` object (slice 13 §4, design §23 "Chunked transfers"): each upload one file handle in
+// the run's directory, written at positions. An append is accepted at the offset the accepted appends reached, so a
+// writer may send several without waiting (the call window allows it): each write lands at its own position whatever
+// order the thread pool completes them in. `uploaded`, `finish` and expiry wait for an upload's writes in flight; a
+// failed write ends its upload.
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { ChordError } from "../../data/index.js";
+import { invalid } from "../../data/internal.js";
+import { newToken } from "./secrets.js";
+/**
+ * The uploads under way of one `Files` object, in the directory `run` (this object's own, made on first use), at most
+ * `max` at once: each holds a file handle until it ends, so a caller beginning uploads without end would exhaust the
+ * process's descriptors. Each carries its owner's `T` (what the file becomes when it finishes).
+ */
+export class Uploads {
+    #run;
+    #max;
+    #uploads = new Map();
+    constructor(run, max) {
+        this.#run = run;
+        this.#max = max;
+    }
+    /** The bytes accepted by every upload under way (they count against the host's cap). */
+    get size() {
+        let size = 0;
+        for (const upload of this.#uploads.values())
+            size += upload.size;
+        return size;
+    }
+    /** The id of the upload under way whose data `matches`, if any. */
+    find(matches) {
+        for (const [id, upload] of this.#uploads)
+            if (matches(upload.data))
+                return id;
+        return undefined;
+    }
+    /** A new upload carrying `data`: its id; `unavailable` (`busy`) while `max` are under way. */
+    async begin(data) {
+        if (this.#uploads.size >= this.#max) {
+            throw new ChordError({
+                code: "unavailable",
+                reason: "busy",
+                message: `files: ${this.#max} uploads are under way; finish one, or wait for an idle one to expire`,
+            });
+        }
+        const id = newToken(12);
+        await mkdir(this.#run, { recursive: true, mode: 0o700 });
+        const handle = await open(join(this.#run, id), "wx", 0o600);
+        const upload = {
+            data,
+            handle,
+            size: 0,
+            touched: Date.now(),
+            writes: new Set(),
+            failed: false,
+            ended: undefined,
+        };
+        this.#uploads.set(id, upload);
+        return id;
+    }
+    /**
+     * Writes `bytes` at `offset` of upload `id`, which must be where the accepted appends reached (else `invalid`, its
+     * details the expected `{ offset }`); `room(adding, fileSize)` refuses what the caps do not allow, before anything
+     * is accepted. A failed write ends the upload.
+     */
+    async append(id, offset, bytes, room) {
+        const upload = this.#underway(id);
+        if (offset !== upload.size) {
+            throw invalid("args", `files: upload ${id} is at offset ${upload.size}, not ${offset}`, {
+                offset: upload.size,
+            });
+        }
+        room(bytes.length, upload.size + bytes.length);
+        // Accepted now, with no await before the write starts: the next append may follow at once, its write going to
+        // its own position.
+        upload.size += bytes.length;
+        upload.touched = Date.now();
+        const write = upload.handle.write(bytes, 0, bytes.length, offset);
+        upload.writes.add(write);
+        try {
+            await write;
+        }
+        catch (error) {
+            upload.writes.delete(write);
+            if (!upload.failed) {
+                upload.failed = true;
+                this.#uploads.delete(id);
+                await this.#end(upload);
+                await rm(join(this.#run, id), { force: true });
+            }
+            throw error;
+        }
+        upload.writes.delete(write);
+    }
+    /** The bytes of upload `id` written so far, once its writes in flight landed: where a writer resumes. */
+    async uploaded(id) {
+        const upload = this.#underway(id);
+        await Promise.allSettled([...upload.writes]);
+        if (upload.failed)
+            throw failedUpload(id);
+        return upload.size;
+    }
+    /** Ends upload `id` once its writes landed and moves its file to `path`; refused when a write of it failed. */
+    async finish(id, path) {
+        const upload = this.#underway(id);
+        // Taken out first: an append arriving now finds no upload.
+        this.#uploads.delete(id);
+        await this.#end(upload);
+        if (upload.failed)
+            throw failedUpload(id);
+        await rename(join(this.#run, id), path);
+        return { data: upload.data, size: upload.size };
+    }
+    /** Drops upload `id` once its writes landed (an unknown one: nothing): its writer gave up. */
+    async cancel(id) {
+        const upload = this.#uploads.get(id);
+        if (upload !== undefined)
+            await this.#discard(id, upload);
+    }
+    /** Drops the uploads unwritten for `idleMs`, once their writes landed. */
+    async expire(idleMs) {
+        const now = Date.now();
+        for (const [id, upload] of this.#uploads) {
+            if (now - upload.touched >= idleMs)
+                await this.#discard(id, upload);
+        }
+    }
+    /** Drops every upload under way (their object ended). */
+    async close() {
+        for (const [id, upload] of this.#uploads)
+            await this.#discard(id, upload);
+    }
+    /** The upload `id` under way; else `invalid`. */
+    #underway(id) {
+        const upload = this.#uploads.get(id);
+        if (upload === undefined)
+            throw invalid("args", `files: no upload ${id} (finished, failed, expired or unknown)`);
+        return upload;
+    }
+    /** Takes upload `id` out, closes its file once its writes landed and removes it. */
+    async #discard(id, upload) {
+        this.#uploads.delete(id);
+        await this.#end(upload);
+        await rm(join(this.#run, id), { force: true });
+    }
+    /** Closes `upload`'s file once its writes in flight landed; once, whoever ends it first. */
+    #end(upload) {
+        upload.ended ??= Promise.allSettled([...upload.writes]).then(() => upload.handle.close());
+        return upload.ended;
+    }
+}
+/** The refusal of an upload one of whose writes failed. */
+function failedUpload(id) {
+    return invalid("args", `files: upload ${id} failed to write and was dropped`);
+}
+//# sourceMappingURL=uploads.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.js","sourceRoot":"","sources":["../../../src/node/app/uploads.ts"],"names":[],"mappings":"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","sourcesContent":["// Chunked uploads of one `Files` object (slice 13 §4, design §23 \"Chunked transfers\"): each upload one file handle in\n// the run's directory, written at positions. An append is accepted at the offset the accepted appends reached, so a\n// writer may send several without waiting (the call window allows it): each write lands at its own position whatever\n// order the thread pool completes them in. `uploaded`, `finish` and expiry wait for an upload's writes in flight; a\n// failed write ends its upload.\n\nimport type { FileHandle } from \"node:fs/promises\";\nimport { mkdir, open, rename, rm } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { ChordError } from \"../../data/index.ts\";\nimport { invalid } from \"../../data/internal.ts\";\nimport { newToken } from \"./secrets.ts\";\n\n/** An upload under way: its owner's data, its file, the bytes accepted, its writes in flight, its first failed write, its end. */\ntype Upload<T> = {\n\treadonly data: T;\n\treadonly handle: FileHandle;\n\tsize: number;\n\ttouched: number;\n\treadonly writes: Set<Promise<unknown>>;\n\tfailed: boolean;\n\tended: Promise<void> | undefined;\n};\n\n/** A finished upload: what it was begun with and its size, its bytes moved to the path `finish` was given. */\nexport type Finished<T> = { readonly data: T; readonly size: number };\n\n/**\n * The uploads under way of one `Files` object, in the directory `run` (this object's own, made on first use), at most\n * `max` at once: each holds a file handle until it ends, so a caller beginning uploads without end would exhaust the\n * process's descriptors. Each carries its owner's `T` (what the file becomes when it finishes).\n */\nexport class Uploads<T> {\n\treadonly #run: string;\n\treadonly #max: number;\n\treadonly #uploads = new Map<string, Upload<T>>();\n\n\tconstructor(run: string, max: number) {\n\t\tthis.#run = run;\n\t\tthis.#max = max;\n\t}\n\n\t/** The bytes accepted by every upload under way (they count against the host's cap). */\n\tget size(): number {\n\t\tlet size = 0;\n\t\tfor (const upload of this.#uploads.values()) size += upload.size;\n\t\treturn size;\n\t}\n\n\t/** The id of the upload under way whose data `matches`, if any. */\n\tfind(matches: (data: T) => boolean): string | undefined {\n\t\tfor (const [id, upload] of this.#uploads) if (matches(upload.data)) return id;\n\t\treturn undefined;\n\t}\n\n\t/** A new upload carrying `data`: its id; `unavailable` (`busy`) while `max` are under way. */\n\tasync begin(data: T): Promise<string> {\n\t\tif (this.#uploads.size >= this.#max) {\n\t\t\tthrow new ChordError({\n\t\t\t\tcode: \"unavailable\",\n\t\t\t\treason: \"busy\",\n\t\t\t\tmessage: `files: ${this.#max} uploads are under way; finish one, or wait for an idle one to expire`,\n\t\t\t});\n\t\t}\n\t\tconst id = newToken(12);\n\t\tawait mkdir(this.#run, { recursive: true, mode: 0o700 });\n\t\tconst handle = await open(join(this.#run, id), \"wx\", 0o600);\n\t\tconst upload: Upload<T> = {\n\t\t\tdata,\n\t\t\thandle,\n\t\t\tsize: 0,\n\t\t\ttouched: Date.now(),\n\t\t\twrites: new Set(),\n\t\t\tfailed: false,\n\t\t\tended: undefined,\n\t\t};\n\t\tthis.#uploads.set(id, upload);\n\t\treturn id;\n\t}\n\n\t/**\n\t * Writes `bytes` at `offset` of upload `id`, which must be where the accepted appends reached (else `invalid`, its\n\t * details the expected `{ offset }`); `room(adding, fileSize)` refuses what the caps do not allow, before anything\n\t * is accepted. A failed write ends the upload.\n\t */\n\tasync append(\n\t\tid: string,\n\t\toffset: number,\n\t\tbytes: Uint8Array,\n\t\troom: (adding: number, fileSize: number) => void,\n\t): Promise<void> {\n\t\tconst upload = this.#underway(id);\n\t\tif (offset !== upload.size) {\n\t\t\tthrow invalid(\"args\", `files: upload ${id} is at offset ${upload.size}, not ${offset}`, {\n\t\t\t\toffset: upload.size,\n\t\t\t});\n\t\t}\n\t\troom(bytes.length, upload.size + bytes.length);\n\t\t// Accepted now, with no await before the write starts: the next append may follow at once, its write going to\n\t\t// its own position.\n\t\tupload.size += bytes.length;\n\t\tupload.touched = Date.now();\n\t\tconst write = upload.handle.write(bytes, 0, bytes.length, offset);\n\t\tupload.writes.add(write);\n\t\ttry {\n\t\t\tawait write;\n\t\t} catch (error) {\n\t\t\tupload.writes.delete(write);\n\t\t\tif (!upload.failed) {\n\t\t\t\tupload.failed = true;\n\t\t\t\tthis.#uploads.delete(id);\n\t\t\t\tawait this.#end(upload);\n\t\t\t\tawait rm(join(this.#run, id), { force: true });\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t\tupload.writes.delete(write);\n\t}\n\n\t/** The bytes of upload `id` written so far, once its writes in flight landed: where a writer resumes. */\n\tasync uploaded(id: string): Promise<number> {\n\t\tconst upload = this.#underway(id);\n\t\tawait Promise.allSettled([...upload.writes]);\n\t\tif (upload.failed) throw failedUpload(id);\n\t\treturn upload.size;\n\t}\n\n\t/** Ends upload `id` once its writes landed and moves its file to `path`; refused when a write of it failed. */\n\tasync finish(id: string, path: string): Promise<Finished<T>> {\n\t\tconst upload = this.#underway(id);\n\t\t// Taken out first: an append arriving now finds no upload.\n\t\tthis.#uploads.delete(id);\n\t\tawait this.#end(upload);\n\t\tif (upload.failed) throw failedUpload(id);\n\t\tawait rename(join(this.#run, id), path);\n\t\treturn { data: upload.data, size: upload.size };\n\t}\n\n\t/** Drops upload `id` once its writes landed (an unknown one: nothing): its writer gave up. */\n\tasync cancel(id: string): Promise<void> {\n\t\tconst upload = this.#uploads.get(id);\n\t\tif (upload !== undefined) await this.#discard(id, upload);\n\t}\n\n\t/** Drops the uploads unwritten for `idleMs`, once their writes landed. */\n\tasync expire(idleMs: number): Promise<void> {\n\t\tconst now = Date.now();\n\t\tfor (const [id, upload] of this.#uploads) {\n\t\t\tif (now - upload.touched >= idleMs) await this.#discard(id, upload);\n\t\t}\n\t}\n\n\t/** Drops every upload under way (their object ended). */\n\tasync close(): Promise<void> {\n\t\tfor (const [id, upload] of this.#uploads) await this.#discard(id, upload);\n\t}\n\n\t/** The upload `id` under way; else `invalid`. */\n\t#underway(id: string): Upload<T> {\n\t\tconst upload = this.#uploads.get(id);\n\t\tif (upload === undefined) throw invalid(\"args\", `files: no upload ${id} (finished, failed, expired or unknown)`);\n\t\treturn upload;\n\t}\n\n\t/** Takes upload `id` out, closes its file once its writes landed and removes it. */\n\tasync #discard(id: string, upload: Upload<T>): Promise<void> {\n\t\tthis.#uploads.delete(id);\n\t\tawait this.#end(upload);\n\t\tawait rm(join(this.#run, id), { force: true });\n\t}\n\n\t/** Closes `upload`'s file once its writes in flight landed; once, whoever ends it first. */\n\t#end(upload: Upload<T>): Promise<void> {\n\t\tupload.ended ??= Promise.allSettled([...upload.writes]).then(() => upload.handle.close());\n\t\treturn upload.ended;\n\t}\n}\n\n/** The refusal of an upload one of whose writes failed. */\nfunction failedUpload(id: string): Error {\n\treturn invalid(\"args\", `files: upload ${id} failed to write and was dropped`);\n}\n"]}

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

@@ -0,0 +1,37 @@
+import { type Schema } from "../../contracts/index.ts";
+import type { Principal } from "../../data/index.ts";
+import { type Facet } from "../../host/index.ts";
+import type { JsonValue } from "../../json.ts";
+/** The users plugin for profiles of schema `profile`: its contract and the facet serving it on the server. */
+export declare function defineUsers<T extends JsonValue, P extends Principal = Principal>(profile: Schema<T>): {
+    Users: import("../../contracts/contract.ts").Contract<{
+        kind: "local";
+        name: "chord.app.users";
+        params: {};
+        history: [{
+            version: "1";
+            variants: {
+                members: {
+                    state: {
+                        readonly list: Schema<{
+                            id: string;
+                            profile: unknown extends T ? T : T;
+                        }[]>;
+                    };
+                    methods: {
+                        readonly get: import("../../contracts/schema.ts").Method<import("../../contracts/schema.ts").StringSchema, Schema<(unknown extends T ? T : T) | null>>;
+                        readonly update: import("../../contracts/schema.ts").Method<Schema<{
+                            id: string;
+                            profile: unknown extends T ? T : T;
+                        }>, import("../../contracts/schema.ts").NullSchema>;
+                        readonly remove: import("../../contracts/schema.ts").Method<import("../../contracts/schema.ts").StringSchema, import("../../contracts/schema.ts").NullSchema>;
+                    };
+                    keyed: {};
+                };
+            };
+            changes: never;
+        }];
+    }>;
+    facet: Facet<P>;
+};
+//# sourceMappingURL=users.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../../src/node/app/users.ts"],"names":[],"mappings":"AAOA,OAAO,EAAqC,KAAK,MAAM,EAAc,MAAM,0BAA0B,CAAC;AACtG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,8GAA8G;AAC9G,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoDnG"}

package/dist/node/app/users.js

@@ -0,0 +1,62 @@
+// The users plugin (slice 13 §3, decision "The app kit, point 2: principals and users"): accounts keyed by the user's
+// id with a profile the app describes (a schema it passes in: a Slack-like profile or just a name), kept in the
+// server's store. User data never rides in the principal: a principal names the user, `Users` holds the rest.
+// An exported facet, not a plugin directory: it takes the app's schema as an argument (settings are arguments), and a
+// plugin directory could not import it (plugins import only the app's API). The app loads it in its root by
+// re-exporting it through its API (`export const users = defineUsers(Profile)` in `/v3/server`, a one-line plugin).
+import { arr, local, map, method, nul, obj, str, union } from "../../contracts/index.js";
+import { invalid } from "../../data/internal.js";
+import { defineState } from "../../documents/index.js";
+import { defineFacet } from "../../host/index.js";
+/** The users plugin for profiles of schema `profile`: its contract and the facet serving it on the server. */
+export function defineUsers(profile) {
+    const Users = local("chord.app.users", {
+        version: 1,
+        params: {},
+        members: {
+            /** Every user: id and profile. */
+            list: arr(obj({ id: str(), profile })),
+            /** The profile of user `id`, or `null`. */
+            get: method(str(), union([profile, nul()])),
+            /** Sets the profile of user `id` (a new user: an account made). */
+            update: method(obj({ id: str(), profile })),
+            /** Removes user `id`'s account. */
+            remove: method(str()),
+        },
+    });
+    // Stored as JSON: the document's types cannot follow a generic profile, the contract's members do.
+    const stored = profile;
+    const Accounts = defineState("chord.app.users", {
+        schema: obj({ users: map(stored) }),
+        version: 1,
+        initial: () => ({ users: {} }),
+        persist: true,
+        checkpointWhen: (_value, _ops, { deltasSinceBase }) => deltasSinceBase >= 50,
+    });
+    const facet = defineFacet((host) => host.serve(Users, (_params, self) => {
+        const accounts = self.state(Accounts);
+        return {
+            list: self.derive([accounts], ([value]) => Object.entries(value.users).map(([id, each]) => ({ id, profile: each }))),
+            // A trust boundary: `id` is the caller's (`Object.hasOwn`: no inherited member is a user). Written by
+            // `update` from a `T`.
+            get: async (id) => (Object.hasOwn(accounts.value.users, id) ? accounts.value.users[id] : null),
+            update: async ({ id, profile: next }, ctx) => {
+                // As a key it would set the record's prototype, not add a user.
+                if (id === "__proto__")
+                    throw invalid("args", "users: __proto__ is no user id");
+                await accounts.change((draft) => {
+                    draft.users[id] = next;
+                }, ctx);
+                return null;
+            },
+            remove: async (id, ctx) => {
+                await accounts.change((draft) => {
+                    delete draft.users[id];
+                }, ctx);
+                return null;
+            },
+        };
+    }));
+    return { Users, facet };
+}
+//# sourceMappingURL=users.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"users.js","sourceRoot":"","sources":["../../../src/node/app/users.ts"],"names":[],"mappings":"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","sourcesContent":["// The users plugin (slice 13 §3, decision \"The app kit, point 2: principals and users\"): accounts keyed by the user's\n// id with a profile the app describes (a schema it passes in: a Slack-like profile or just a name), kept in the\n// server's store. User data never rides in the principal: a principal names the user, `Users` holds the rest.\n// An exported facet, not a plugin directory: it takes the app's schema as an argument (settings are arguments), and a\n// plugin directory could not import it (plugins import only the app's API). The app loads it in its root by\n// re-exporting it through its API (`export const users = defineUsers(Profile)` in `/v3/server`, a one-line plugin).\n\nimport { arr, local, map, method, nul, obj, type Schema, str, union } from \"../../contracts/index.ts\";\nimport type { Principal } from \"../../data/index.ts\";\nimport { invalid } from \"../../data/internal.ts\";\nimport { defineState } from \"../../documents/index.ts\";\nimport { defineFacet, type Facet } from \"../../host/index.ts\";\nimport type { JsonValue } from \"../../json.ts\";\n\n/** The users plugin for profiles of schema `profile`: its contract and the facet serving it on the server. */\nexport function defineUsers<T extends JsonValue, P extends Principal = Principal>(profile: Schema<T>) {\n\tconst Users = local(\"chord.app.users\", {\n\t\tversion: 1,\n\t\tparams: {},\n\t\tmembers: {\n\t\t\t/** Every user: id and profile. */\n\t\t\tlist: arr(obj({ id: str(), profile })),\n\t\t\t/** The profile of user `id`, or `null`. */\n\t\t\tget: method(str(), union([profile, nul()])),\n\t\t\t/** Sets the profile of user `id` (a new user: an account made). */\n\t\t\tupdate: method(obj({ id: str(), profile })),\n\t\t\t/** Removes user `id`'s account. */\n\t\t\tremove: method(str()),\n\t\t},\n\t});\n\t// Stored as JSON: the document's types cannot follow a generic profile, the contract's members do.\n\tconst stored = profile as Schema<JsonValue>;\n\tconst Accounts = defineState(\"chord.app.users\", {\n\t\tschema: obj({ users: map(stored) }),\n\t\tversion: 1,\n\t\tinitial: () => ({ users: {} }),\n\t\tpersist: true,\n\t\tcheckpointWhen: (_value, _ops, { deltasSinceBase }) => deltasSinceBase >= 50,\n\t});\n\tconst facet: Facet<P> = defineFacet<P>((host) =>\n\t\thost.serve(Users, (_params, self) => {\n\t\t\tconst accounts = self.state(Accounts);\n\t\t\treturn {\n\t\t\t\tlist: self.derive([accounts], ([value]) =>\n\t\t\t\t\tObject.entries(value.users).map(([id, each]) => ({ id, profile: each as T })),\n\t\t\t\t),\n\t\t\t\t// A trust boundary: `id` is the caller's (`Object.hasOwn`: no inherited member is a user). Written by\n\t\t\t\t// `update` from a `T`.\n\t\t\t\tget: async (id) => (Object.hasOwn(accounts.value.users, id) ? (accounts.value.users[id] as T) : null),\n\t\t\t\tupdate: async ({ id, profile: next }, ctx) => {\n\t\t\t\t\t// As a key it would set the record's prototype, not add a user.\n\t\t\t\t\tif (id === \"__proto__\") throw invalid(\"args\", \"users: __proto__ is no user id\");\n\t\t\t\t\tawait accounts.change((draft) => {\n\t\t\t\t\t\tdraft.users[id] = next as JsonValue;\n\t\t\t\t\t}, ctx);\n\t\t\t\t\treturn null;\n\t\t\t\t},\n\t\t\t\tremove: async (id, ctx) => {\n\t\t\t\t\tawait accounts.change((draft) => {\n\t\t\t\t\t\tdelete draft.users[id];\n\t\t\t\t\t}, ctx);\n\t\t\t\t\treturn null;\n\t\t\t\t},\n\t\t\t};\n\t\t}),\n\t);\n\treturn { Users, facet };\n}\n"]}