copilotz 1.0.0-rc.21 → 1.0.0-rc.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,71 @@
1
+ ## 1.0.0-rc.22 — 2026-11-04
2
+
3
+ **A security release: upgrade now.** Before it, a Google sign-in wrote the new session's secret to
4
+ the event log, and connecting a computer wrote the computer's secret (the first entry below). After
5
+ upgrading, every deployment should:
6
+
7
+ 1. **End every session made before the upgrade:** delete the `credential` documents of
8
+ `kind: "session"`, so every signed-in person signs in again. Keys are unaffected.
9
+ 2. **Scrub the old events that hold these secrets**, from the store and from anything that copied it
10
+ (backups, exports, exporters): the `action.started` and `action.completed` events of
11
+ `google.sign-in`, `computer.code`, `computer.enrollment` and `computer.work`, and the
12
+ `action.started` events of `session.end`, `computer.admit`, `pool.admit` and `pool.serve`.
13
+ 3. **Reconnect computers whose log may have been read:** forget each one (`computer.forget`) and
14
+ connect it again with a new code. A computer's secret can't be rotated yet.
15
+
16
+ - **Security: a Google sign-in no longer writes the session's secret to the log.** `google.sign-in`
17
+ was a recorded Action, so the event log kept its input, the Google ID token, and its result,
18
+ `{ person, session }`, with the new session's secret in plain text. Anyone who could read the log
19
+ (a database reader, a backup, an export, an exporter) could sign in as that person, staff
20
+ included. The identity plugin keeps secrets only as hashes, and this Action undid that. It is now
21
+ unrecorded (`record: false`), like `session.start`. So is `session.end`, whose input is the secret
22
+ being ended. Found by a security review.
23
+ - **Computers' secrets are kept out of the log too**, found by checking every Action for the same
24
+ mistake. These are now unrecorded: `computer.admit`, whose input is a computer's secret (or the
25
+ code connecting it) on every connect; `pool.admit`, whose input is a pool VM's identity token;
26
+ `computer.code`, whose result is the code that connects a computer as its person; and
27
+ `computer.work`, whose input and result are what a person types and sees in their shell, files'
28
+ contents and the env values they pass. `computer.enrollment`'s result (`code`) and
29
+ `pool.serve`'s `assign.code` and `assign.secret` (also when forwarded by `remotePool`) are
30
+ private: still recorded, so a retried wake gets the same code, but the code isn't logged.
31
+ - **Deployments should end every session made before this fix.** Delete the `credential` documents
32
+ of `kind: "session"`, so every signed-in person signs in again. Keys are unaffected. A
33
+ computer's secret can't be rotated yet: where the log may have been read, forget the computer
34
+ (`computer.forget`) and connect it again with a new code.
35
+ - **Old events still hold these secrets until they're scrubbed**, from the store and from anything
36
+ that copied it: the `action.started` and `action.completed` events of `google.sign-in`,
37
+ `computer.code`, `computer.enrollment` and `computer.work`, and the `action.started` events of
38
+ `session.end`, `computer.admit`, `pool.admit` and `pool.serve`. Ended sessions, used codes and
39
+ expired tokens prove nobody, but scrub them anyway.
40
+
41
+ - **MCP: a conversation whose first call an owner stopped no longer ends for good.** A new
42
+ conversation's chat is made (`chat.open`) and then shared with its contact (`member.set`), two
43
+ writes; an owner that stopped between them (a deploy, which doesn't wait for running calls, or a
44
+ crash) left a chat its contact couldn't reach, which is how a contact its people took out of its
45
+ chat looks, so every later call said "This conversation with the app is over". A new
46
+ conversation's opening is now noted with its first call's counts (`mcp_opening`, durable, no
47
+ events, gone with its receipts after 15 minutes) and dropped once the chat is shared: a chat out
48
+ of its contact's reach, with its opening noted, goes on as new (asked again within 15 minutes, its
49
+ contact not erased); without one, it stays over. Erasure's tombstones are read first, as before.
50
+ This is what failed the MCP restart test on slower machines (macOS CI); the test now waits on what
51
+ it watches for, not on fixed times, and a new one stops an owner at each of a first call's writes.
52
+ - **Contacts: a start cut short after a contact's record, before sharing it with the contact, is
53
+ finished when it's started again** (`contact.start`, on WhatsApp, voice and MCP): the contact, and
54
+ the agent working for it, read the record again. A known contact was returned as it was.
55
+ - **Maintenance SQL can run as the store's own role, told so:**
56
+ `postgresStore({ url, schema, maintenance: { storeRole: true } })`, beside a role of its own
57
+ (`maintenance: { url }`; both at once stop the store from opening, and neither still refuses raw
58
+ SQL on a server, its message naming both). Anyone holding the maintenance key can then do whatever
59
+ the store's role can: drop or truncate its tables, delete from the log, read every schema it
60
+ reaches. Only the allowlist check is skipped; the statement filter, a connection of its own for
61
+ each statement over the extended protocol, the timeouts, caps and `connections`, fenced writes in
62
+ the owner with their `maintenance.sql` event, the rollback of what changes `meta` or makes a
63
+ trigger, and the emptied cache all hold. Still refused, before each statement and after a write: a
64
+ role that is or may become a superuser, a member of `pg_execute_server_program`,
65
+ `pg_read_server_files` or `pg_write_server_files`, one with `CREATEROLE` before PostgreSQL 16, or
66
+ one that may run the server's file functions (`pg_read_file`, `lo_import`, `lo_export`…). Cloud
67
+ SQL's `postgres` user passes from PostgreSQL 16. An orgs host's orgs still don't get the plugin.
68
+
1
69
  ## 1.0.0-rc.21 — 2026-11-04
2
70
 
3
71
  - **Security: a burst of calls no longer drops an executor's connection** (Oxian 0.23.3). About 35
@@ -265,7 +333,7 @@
265
333
  app's `links`, uploaded to Meta and sent by its id). A carousel's pictures must be links: a file
266
334
  with nowhere to link it sends the fallback. A message's files go as images (jpeg, png up to 5
267
335
  MB) or documents, a short text as the first one's caption.
268
- - **WhatsApp lines for an app, as it uses them** (for Mobizap):
336
+ - **WhatsApp lines for an app, as it uses them**:
269
337
  - **A line the app declares** in its settings (`resources.whatsapp.lines.<name>`: the space,
270
338
  Meta's number id, token and app secret, its own verify token, a webhook path it routes to
271
339
  `whatsapp.hook`, its agent, gap, rate, quiet window and language): open to anyone, kept as the
package/README.md CHANGED
@@ -22,7 +22,7 @@ bun add copilotz # Bun
22
22
  deno add jsr:@copilotz/copilotz # Deno (or `deno add npm:copilotz`)
23
23
  ```
24
24
 
25
- On Deno, name it `copilotz` in `deno.json` (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.21"`),
25
+ On Deno, name it `copilotz` in `deno.json` (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.22"`),
26
26
  and the imports below are the same everywhere. Some pieces need a package of their own, installed
27
27
  beside it: `esbuild` to bundle the web host on Node, `@electric-sql/pglite` for PostgreSQL in the
28
28
  process, and `@types/react` for the front ends' types.
@@ -247,7 +247,7 @@ and an app serves it from there by default:
247
247
  import { computerDownloads } from "copilotz/plugins/compute/downloads";
248
248
 
249
249
  plugins: [...plugins, await computerDownloads()], // this Copilotz's release
250
- plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.21" })], // its own: /computer/download/
250
+ plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.22" })], // its own: /computer/download/
251
251
  plugins: [...plugins, await computerDownloads({ url: "https://downloads.example.com/computer/" })], // or elsewhere
252
252
  ```
253
253
 
@@ -712,18 +712,19 @@ curl https://app.example.com/maintenance/sql -H "authorization: Bearer $KEY" \
712
712
  `inline: true`. SQLite writes name the store's tables in `main`, so nothing temporary stands in
713
713
  for them. Each store runs at most 2 maintenance statements at once
714
714
  (`maintenance: { connections }`): another answers busy (503).
715
- - **Where:** SQL needs a SQL store. On a PostgreSQL server only as a role of its own (below), never
716
- in a schema other tenants share; PGlite, in the app's process, runs it as its one session where it
717
- reaches no other schema. An orgs host's orgs don't get the plugin at all (one key would reach
718
- every org). Operations, named queries and blobs work everywhere, the memory store too, and need no
719
- role.
715
+ - **Where:** SQL needs a SQL store. On a PostgreSQL server only as a role of its own (below) or,
716
+ told so, as the store's own role (below that), never in a schema other tenants share; PGlite, in
717
+ the app's process, runs it as its one session where it reaches no other schema. An orgs host's
718
+ orgs don't get the plugin at all (one key would reach every org). Operations, named queries and
719
+ blobs work everywhere, the memory store too, and need no role.
720
720
 
721
721
  ### A role of its own
722
722
 
723
723
  On a PostgreSQL server, raw SQL runs only as a role of its own, named by the store:
724
724
  `postgresStore({ url, schema, maintenance: { url: process.env.MAINTENANCE_DATABASE_URL } })`.
725
- Without one it's refused. The store's role owns the tables, may stop the app's connections and is
726
- whatever the deployment made it (a superuser, even): nothing that runs at a key's word should be it.
725
+ Without one it's refused, unless the store is told to run it as its own role (below). The store's
726
+ role owns the tables, may stop the app's connections and is whatever the deployment made it (a
727
+ superuser, even): nothing that runs at a key's word should be it.
727
728
 
728
729
  Before each statement, on the connection that runs it, and again after a write in its transaction,
729
730
  maintenance checks that the role holds exactly what the SQL below grants, and refuses it otherwise
@@ -792,6 +793,34 @@ SELECT p.oid::regprocedure FROM pg_proc p WHERE p.prosecdef
792
793
  REVOKE EXECUTE ON FUNCTION some_schema.some_function(…) FROM PUBLIC;
793
794
  ```
794
795
 
796
+ ### Or the store's own role
797
+
798
+ Where a role of its own is more than a deployment wants, raw SQL can run as the store's own role
799
+ instead, said in so many words: `postgresStore({ url, schema, maintenance: { storeRole: true } })`
800
+ (`connections` as above). Each statement then connects as the role in the store's `url` (or its
801
+ pool's). Naming `url` and `storeRole` together stops the store from opening.
802
+
803
+ **What it costs:** anyone holding the maintenance key can do whatever the store's role can. It owns
804
+ the store's tables, so a statement can drop or truncate them, delete from the log, or rewrite any
805
+ document without an event; it can read every schema the role reaches (another app's on the same
806
+ database too, if it may), stop the app's own connections, and create roles or databases if the role
807
+ may. A leaked key is then almost the app's own database login. Only the check above is skipped,
808
+ which the store's role couldn't pass. Everything else holds: the statement filter (no `COMMIT`,
809
+ `SET`, `ALTER ROLE`, `DO`, `LOCK`…); the extended protocol and a connection of its own for each
810
+ statement, closed after; timeouts, the row and byte caps, and at most `connections` at once; writes
811
+ inside the owner, fenced, with their `maintenance.sql` event; a statement that changes `meta` or
812
+ makes a trigger rolled back; the owner's cache emptied after a write; the key and the log line.
813
+
814
+ Still refused, before each statement and again after a write in its transaction, saying why: a role
815
+ that could turn SQL into commands on the database server or access to its files. That is a
816
+ superuser; a member, by any path, of a superuser role (it could switch to it within a statement), or
817
+ of `pg_execute_server_program`, `pg_read_server_files` or `pg_write_server_files`; before PostgreSQL
818
+ 16, one with `CREATEROLE` (enough to grant itself any of those); and one that may run
819
+ `pg_read_file`, `pg_read_binary_file`, `lo_import`, `lo_export` or adminpack's file functions. Cloud
820
+ SQL's `postgres` user isn't a superuser (it's a member of `cloudsqlsuperuser`, which isn't one
821
+ either): from PostgreSQL 16 it passes; on 15 or earlier its `CREATEROLE` is refused, so use a role
822
+ of its own there.
823
+
795
824
  ## The example app
796
825
 
797
826
  `examples/terminal-agent` is an app on all of it: an assistant and a researcher, notes in spaces,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "copilotz",
3
- "version": "1.0.0-rc.21",
3
+ "version": "1.0.0-rc.22",
4
4
  "description": "Copilotz: one runtime for Node, Deno, Bun, Cloudflare Workers and the browser.",
5
5
  "keywords": [
6
6
  "agents",
@@ -4,9 +4,12 @@
4
4
  * proved who they are (Meta's signed webhook names the phone), with an id
5
5
  * from what brought them (`id`), so a retry makes the same one; starting
6
6
  * one that exists changes only its name, if that changed. Its record is
7
- * shared with it on its own (it reads it, and the agent working for it does).
7
+ * shared with it on its own (it reads it, and the agent working for it
8
+ * does): a start cut short between the two (an owner restarted) shares it
9
+ * when it's started again.
8
10
  */
9
11
  import { defineAction } from "../../../../runtime/mod.js";
12
+ import { CONTACT } from "../collections/contact.js";
10
13
  export const startAction = defineAction({
11
14
  description: "Makes a contact: someone outside the org who came by a line",
12
15
  input: {
@@ -26,10 +29,22 @@ export const startAction = defineAction({
26
29
  const contacts = ctx.db.collection("contact");
27
30
  const id = input.id ?? `c-${crypto.randomUUID()}`;
28
31
  const name = input.name?.trim();
29
- const known = await contacts.findOne({ _id: id });
32
+ const share = () => ctx.call("member.set", {
33
+ space: id,
34
+ on: "contact",
35
+ member: { kind: "contact", id },
36
+ role: "viewer",
37
+ });
38
+ // Its record, and its share of it (the record's own key, and the contact's).
39
+ const [known, shared] = await Promise.all([
40
+ contacts.findOne({ _id: id }),
41
+ ctx.as().db.collection("member").findOne({ _id: `${CONTACT}${id}|${CONTACT}${id}` }),
42
+ ]);
30
43
  if (known) {
31
44
  if (name && known.name !== name)
32
45
  await contacts.updateOne({ _id: id }, { $set: { name } });
46
+ if (!shared)
47
+ await share();
33
48
  return { contact: id };
34
49
  }
35
50
  await contacts.insertOne({
@@ -39,12 +54,7 @@ export const startAction = defineAction({
39
54
  ...(name ? { name } : {}),
40
55
  at: new Date().toISOString(),
41
56
  });
42
- await ctx.call("member.set", {
43
- space: id,
44
- on: "contact",
45
- member: { kind: "contact", id },
46
- role: "viewer",
47
- });
57
+ await share();
48
58
  return { contact: id };
49
59
  },
50
60
  });
@@ -9,6 +9,8 @@ import { verify } from "../shared/jwt.js";
9
9
  import { settingsOf } from "../shared/settings.js";
10
10
  export const signInAction = defineAction({
11
11
  description: "Signs in with a Google ID token: the person, and a new session",
12
+ // Unrecorded: its input is the ID token and its result the session's secret.
13
+ record: false,
12
14
  input: {
13
15
  type: "object",
14
16
  properties: { idToken: { type: "string" } },
@@ -35,6 +35,8 @@ export const startSession = defineAction({
35
35
  });
36
36
  export const endSession = defineAction({
37
37
  description: "Ends the session whose secret is shown",
38
+ // Unrecorded: its input is the secret.
39
+ record: false,
38
40
  input: {
39
41
  type: "object",
40
42
  properties: { session: { type: "string" } },
@@ -6,7 +6,7 @@
6
6
  * the app's, so people neither rename it nor take its agents out.
7
7
  *
8
8
  * ```ts
9
- * resources: { spaces: { line: { name: "Mobifácil", agents: ["booking"] } } }
9
+ * resources: { spaces: { line: { name: "Viação Azul", agents: ["booking"] } } }
10
10
  * ```
11
11
  */
12
12
  import type { Context } from "../../../../runtime/mod.js";
@@ -40,6 +40,8 @@ async function seen(ctx, vm, state) {
40
40
  return null;
41
41
  }
42
42
  export const poolAdmitAction = defineAction({
43
+ // Unrecorded: its input is the VM's identity token, which admits it.
44
+ record: false,
43
45
  input: {
44
46
  type: "object",
45
47
  properties: { secret: { type: "string" } },
@@ -9,14 +9,16 @@ import { defineAction } from "../../../../runtime/mod.js";
9
9
  import { POOL_ACTIONS } from "../contract.js";
10
10
  /** The forwarding Actions, by name: `pool.take`, `pool.serve`, `pool.stop`, `pool.drop`, `pool.renew`. */
11
11
  export function remoteActions(call, org) {
12
- const forward = (action, record = true) => defineAction({
12
+ const forward = (action, record = true, hidden = []) => defineAction({
13
13
  ...(record ? {} : { record: false }),
14
+ ...(hidden.length ? { private: hidden } : {}),
14
15
  input: { type: "object" },
15
16
  run: (_ctx, input) => call(action, org !== undefined ? { ...input, org } : input),
16
17
  });
17
18
  return {
18
19
  [POOL_ACTIONS.take]: forward(POOL_ACTIONS.take),
19
- [POOL_ACTIONS.serve]: forward(POOL_ACTIONS.serve),
20
+ // What connects the computer stays out of the log, as the pool's own `pool.serve`.
21
+ [POOL_ACTIONS.serve]: forward(POOL_ACTIONS.serve, true, ["assign.code", "assign.secret"]),
20
22
  [POOL_ACTIONS.stop]: forward(POOL_ACTIONS.stop),
21
23
  [POOL_ACTIONS.drop]: forward(POOL_ACTIONS.drop),
22
24
  [POOL_ACTIONS.renew]: forward(POOL_ACTIONS.renew, false),
@@ -120,6 +120,8 @@ export const takeAction = defineAction({
120
120
  },
121
121
  });
122
122
  export const serveAction = defineAction({
123
+ // What connects the computer stays out of the log.
124
+ private: ["assign.code", "assign.secret"],
123
125
  input: {
124
126
  type: "object",
125
127
  properties: { vm: { type: "string" }, assign: { type: "object" }, org: { type: "string" } },
@@ -9,6 +9,8 @@ import { defineAction } from "../../../../runtime/mod.js";
9
9
  import { deskIn } from "../shared/desks.js";
10
10
  import { hash, same, secret } from "../shared/secret.js";
11
11
  export const admitAction = defineAction({
12
+ // Unrecorded: its input is the computer's secret, or a code to connect one.
13
+ record: false,
12
14
  input: {
13
15
  type: "object",
14
16
  properties: { secret: { type: "string" } },
@@ -16,6 +16,8 @@ import { settingsOf } from "../shared/settings.js";
16
16
  import { must } from "../../../access/spaces/contract.js";
17
17
  export const codeAction = defineAction({
18
18
  description: "A one-time code to connect a computer to a space",
19
+ // Unrecorded: its result is the code, which connects a computer as the person.
20
+ record: false,
19
21
  input: {
20
22
  type: "object",
21
23
  properties: { in: { type: "string" } },
@@ -12,6 +12,8 @@ import { defineAction } from "../../../../runtime/mod.js";
12
12
  import { code, hash } from "../shared/secret.js";
13
13
  import { settingsOf } from "../shared/settings.js";
14
14
  export const enrollmentAction = defineAction({
15
+ // Recorded, so a retried wake gets the same code; the code itself stays out of the log.
16
+ private: ["code"],
15
17
  input: {
16
18
  type: "object",
17
19
  properties: { computer: { type: "string" } },
@@ -32,6 +32,9 @@ const PANEL = {
32
32
  const READS = new Set(["jobs.list", "jobs.logs", "files.list", "files.read", "search"]);
33
33
  export const workAction = defineAction({
34
34
  description: "Works on a space's computer, in its folder there",
35
+ // Unrecorded: what's typed and shown in a shell, files' contents and env values
36
+ // given over the space's pass through; they often hold secrets.
37
+ record: false,
35
38
  input: {
36
39
  type: "object",
37
40
  properties: {
@@ -1,2 +1,2 @@
1
1
  /** The computer program's version, as `computer.info` and `--version` say it, and its builds are named. */
2
- export declare const VERSION = "1.0.0-rc.21";
2
+ export declare const VERSION = "1.0.0-rc.22";
@@ -1,2 +1,2 @@
1
1
  /** The computer program's version, as `computer.info` and `--version` say it, and its builds are named. */
2
- export const VERSION = "1.0.0-rc.21";
2
+ export const VERSION = "1.0.0-rc.22";
@@ -14,7 +14,7 @@
14
14
  *
15
15
  * ```ts
16
16
  * plugins: [...plugins, await computerDownloads()]
17
- * plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.21" })]
17
+ * plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.22" })]
18
18
  * plugins: [...plugins, await computerDownloads({ url: "https://downloads.example.com/computer/" })]
19
19
  * ```
20
20
  */
@@ -18,7 +18,9 @@
18
18
  * - **Read SQL**, one read-only statement (`runtime.maintenance.read`, the
19
19
  * store's `inspect`): at most `limit` rows and `bytes`, cut off after
20
20
  * `timeout`. On a PostgreSQL server, as a role of its own
21
- * (`postgresStore({ maintenance: { url } })`; the README's Maintenance).
21
+ * (`postgresStore({ maintenance: { url } })`), or, told so, as the
22
+ * store's own (`maintenance: { storeRole: true }`); the README's
23
+ * Maintenance says what each costs.
22
24
  * - **Writes through the owner**: the collections' operations (insertOne…
23
25
  * deleteMany, and find…aggregate), checked against their schemas, recorded
24
26
  * as events, cached and heard by Processors like any write; and the
@@ -18,7 +18,9 @@
18
18
  * - **Read SQL**, one read-only statement (`runtime.maintenance.read`, the
19
19
  * store's `inspect`): at most `limit` rows and `bytes`, cut off after
20
20
  * `timeout`. On a PostgreSQL server, as a role of its own
21
- * (`postgresStore({ maintenance: { url } })`; the README's Maintenance).
21
+ * (`postgresStore({ maintenance: { url } })`), or, told so, as the
22
+ * store's own (`maintenance: { storeRole: true }`); the README's
23
+ * Maintenance says what each costs.
22
24
  * - **Writes through the owner**: the collections' operations (insertOne…
23
25
  * deleteMany, and find…aggregate), checked against their schemas, recorded
24
26
  * as events, cached and heard by Processors like any write; and the
@@ -6,9 +6,12 @@
6
6
  * keep it to its own chat. In order:
7
7
  *
8
8
  * 1. **Its chat**, which comes from the contact (see shared/keys.ts): in
9
- * use, or new (the first call of a conversation), or over (erased, or its
10
- * people took the contact out of it: it stays so), or unknown (a handle
11
- * the app never gave: refused). Nothing is counted or made for these.
9
+ * use, or new (the first call of a conversation), or begun (a first call
10
+ * cut short between making the chat and sharing it with the contact, as
11
+ * an owner restarting does: it goes on as new; see
12
+ * collections/opening.ts), or over (erased, or its people took the
13
+ * contact out of it: it stays so), or unknown (a handle the app never
14
+ * gave: refused). Nothing is counted or made for these last two.
12
15
  * 2. **The line's limits:** its conversation's calls a minute, the caller's
13
16
  * address's, the line's; for a new conversation, new ones an hour, the
14
17
  * line's, the user's, the address's. Past one, the call is refused with a
@@ -27,7 +30,8 @@
27
30
  * it always runs.
28
31
  * 5. **A new conversation** is made, as the system: its contact
29
32
  * (`contact.start`, `via: "mcp"`) and its chat in the line's space,
30
- * shared with it on its own (`contact.chat`).
33
+ * shared with it on its own (`contact.chat`). Its opening is noted with
34
+ * the call's counts (`mcp_opening`), and goes once the chat is shared.
31
35
  * 6. **The tool runs** through chat's runner, as the contact: its input
32
36
  * checked, its `ctx.agent` the client (`ChatGPT`), its `ctx.thread` the
33
37
  * chat, its `ctx.callId` and `ctx.trigger` the step (the same however
@@ -69,7 +73,8 @@ const SAID = {
69
73
  hidden: "It ran, but what it returned can't be shown.",
70
74
  };
71
75
  /** Writes whose answer isn't needed: a transaction of only these is one command, never held. */
72
- const UPSERT = { upsert: true, writeConcern: { w: 0 } };
76
+ const UNANSWERED = { writeConcern: { w: 0 } };
77
+ const UPSERT = { upsert: true, ...UNANSWERED };
73
78
  const MINUTE = 60_000;
74
79
  const HOUR = 3_600_000;
75
80
  /** The longest answer a receipt keeps (characters); a longer one is shown again from its step. */
@@ -117,8 +122,8 @@ export const callAction = defineAction({
117
122
  const { calls, chats } = countersOf(line, thread, input, now);
118
123
  const system = ctx.as();
119
124
  // What it needs to know first, read together: its chat (as the system, and as its contact,
120
- // who still reaches it or not), whether it's over, the counts, a receipt.
121
- const [there, reached, over, counted, receipt] = await Promise.all([
125
+ // who still reaches it or not), whether it's over, the counts, a receipt, an opening noted.
126
+ const [there, reached, over, counted, receipt, noted] = await Promise.all([
122
127
  system.db.collection("thread").findOne({ _id: thread }),
123
128
  ctx.db.collection("thread").findOne({ _id: thread }),
124
129
  system.db.collection("mcp_closed").findOne({
@@ -127,12 +132,19 @@ export const callAction = defineAction({
127
132
  system.db.collection("mcp_rate")
128
133
  .find({ _id: { $in: [...calls, ...chats].map((c) => c._id) } }),
129
134
  readOnly ? null : system.db.collection("mcp_receipt").findOne({ _id: same }),
135
+ system.db.collection("mcp_opening").findOne({ _id: thread }),
130
136
  ]);
131
- if (over || (there && !reached))
137
+ if (over)
138
+ return { text: SAID.closed, isError: true, ran: false };
139
+ // A chat out of its contact's reach: its people took the contact out (over), unless its
140
+ // first call was cut short before sharing it (an owner restarted): that opening goes on.
141
+ const begun = !!there && !reached && !!noted && now - noted.at < RERUN_MS &&
142
+ !!await system.db.collection("contact").findOne({ _id: contact });
143
+ if (there && !reached && !begun)
132
144
  return { text: SAID.closed, isError: true, ran: false };
133
145
  if (!there && input.by === "handle")
134
146
  return { text: SAID.unknown, isError: true, ran: false };
135
- const fresh = !there;
147
+ const fresh = !there || begun;
136
148
  const counts = new Map(counted.map((c) => [c._id, c.count]));
137
149
  const past = [...calls, ...fresh ? chats : []].find((c) => (counts.get(c._id) ?? 0) >= c.most);
138
150
  if (past)
@@ -148,7 +160,9 @@ export const callAction = defineAction({
148
160
  const answered = receipt?.done && now - receipt.at < RESEND_MS ? receipt : undefined;
149
161
  const cut = receipt && !receipt.done && now - receipt.at < RERUN_MS ? receipt : undefined;
150
162
  const step = cut?.step ?? `${input.call}@${now.toString(36)}`;
151
- // Taken: counted, and (a tool that changes things) noted before it runs: one command.
163
+ // Taken: counted, and (a tool that changes things) noted before it runs, as a new
164
+ // conversation's opening is before it's made (one cut short just after its share is done
165
+ // now): one command.
152
166
  await system.transaction(async (tx) => {
153
167
  const rates = tx.db.collection("mcp_rate");
154
168
  for (const c of calls) {
@@ -157,6 +171,11 @@ export const callAction = defineAction({
157
171
  if (!readOnly && !answered && !cut) {
158
172
  await tx.db.collection("mcp_receipt").replaceOne({ _id: same }, { step, at: now }, UPSERT);
159
173
  }
174
+ const openings = tx.db.collection("mcp_opening");
175
+ if (fresh && !answered)
176
+ await openings.replaceOne({ _id: thread }, { at: now }, UPSERT);
177
+ else if (noted && !fresh)
178
+ await openings.deleteOne({ _id: thread }, UNANSWERED);
160
179
  });
161
180
  if (answered)
162
181
  return { ...await again(ctx, line, answered), ran: true, again: true };
@@ -278,8 +297,10 @@ async function again(ctx, line, receipt) {
278
297
  /**
279
298
  * A new conversation's contact and chat, as the system: the line's space
280
299
  * (made or kept, when the app declares it), the contact, and its chat
281
- * there, shared with it. Two first calls at once may both try: the one that
282
- * finds the other's work done goes on.
300
+ * there, shared with it; then its opening, noted before, goes. Each step
301
+ * finds what's done already and goes on: two first calls at once may both
302
+ * try, and a first call cut short before the share (an owner restarted)
303
+ * is asked again and does the rest.
283
304
  */
284
305
  async function opened(ctx, line, contact, thread) {
285
306
  const system = ctx.as();
@@ -301,4 +322,6 @@ async function opened(ctx, line, contact, thread) {
301
322
  throw error;
302
323
  await open();
303
324
  }
325
+ // Shared: from here, a chat out of the contact's reach is one its people took it out of.
326
+ await system.db.collection("mcp_opening").deleteOne({ _id: thread });
304
327
  }
@@ -1,12 +1,13 @@
1
1
  /**
2
2
  * `mcp.prune`: what's past goes: counters whose window is over, and receipts
3
- * older than a call cut short is run again for (see collections/). The
4
- * plugin's schedule calls it every ten minutes; nobody outside may.
3
+ * and openings older than a call cut short is run again for (see
4
+ * collections/). The plugin's schedule calls it every ten minutes; nobody
5
+ * outside may.
5
6
  */
6
7
  import { defineAction } from "../../../../runtime/mod.js";
7
8
  import { RERUN_MS } from "../collections/receipt.js";
8
9
  export const pruneAction = defineAction({
9
- description: "Drops MCP's counters and receipts that are past",
10
+ description: "Drops MCP's counters, receipts and openings that are past",
10
11
  input: { type: "object", additionalProperties: false },
11
12
  record: false,
12
13
  run: async (ctx) => {
@@ -14,5 +15,6 @@ export const pruneAction = defineAction({
14
15
  const system = ctx.as().db;
15
16
  await system.collection("mcp_rate").deleteMany({ until: { $lte: now } });
16
17
  await system.collection("mcp_receipt").deleteMany({ at: { $lt: now - RERUN_MS } });
18
+ await system.collection("mcp_opening").deleteMany({ at: { $lt: now - RERUN_MS } });
17
19
  },
18
20
  });
@@ -0,0 +1,24 @@
1
+ export declare const opening: {
2
+ schema: {
3
+ readonly type: "object";
4
+ readonly properties: {
5
+ /** When its first call began (ms). */
6
+ readonly at: {
7
+ readonly type: "integer";
8
+ };
9
+ };
10
+ readonly required: readonly ["at"];
11
+ };
12
+ events?: boolean;
13
+ records?: boolean;
14
+ durable?: false;
15
+ indexes?: string[][];
16
+ private?: string[];
17
+ queries?: Record<string, import("../../../../runtime/define.js").QueryDef<{
18
+ [x: string]: unknown;
19
+ at: number;
20
+ } & {
21
+ _id: string;
22
+ }>> | undefined;
23
+ vectors?: string[];
24
+ };
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Conversations being opened, by their chat's id: noted with a new
3
+ * conversation's first call, before its contact and chat are made, and gone
4
+ * once the chat is shared with the contact. The two are separate writes
5
+ * (`chat.open`, then `member.set`), so an owner that stops between them (a
6
+ * deploy, a crash) leaves a chat its contact can't reach, which is also what
7
+ * a contact its people took out of its chat looks like. This tells them
8
+ * apart: a chat out of its contact's reach is over, unless its opening is
9
+ * noted here, asked again within 15 minutes (as a call begun and never done
10
+ * is), and the contact is still there (not erased); then the opening goes
11
+ * on, as itself. An opening cut short just after the share is done by the
12
+ * conversation's next call, which finds its chat shared. No events, no
13
+ * personal data (the id is an HMAC); what's older than that goes
14
+ * (`mcp.prune`).
15
+ */
16
+ import { defineCollection } from "../../../../runtime/mod.js";
17
+ export const opening = defineCollection({
18
+ schema: {
19
+ type: "object",
20
+ properties: {
21
+ /** When its first call began (ms). */
22
+ at: { type: "integer" },
23
+ },
24
+ required: ["at"],
25
+ },
26
+ events: false,
27
+ indexes: [["at"]],
28
+ });
@@ -82,6 +82,7 @@ import { definePlugin, linksOf } from "../../../runtime/mod.js";
82
82
  import { callAction } from "./actions/call.js";
83
83
  import { pruneAction } from "./actions/prune.js";
84
84
  import { closed } from "./collections/closed.js";
85
+ import { opening } from "./collections/opening.js";
85
86
  import { rate } from "./collections/rate.js";
86
87
  import { receipt } from "./collections/receipt.js";
87
88
  import { erasedProcessor, forgottenProcessor } from "./processors/closed.js";
@@ -92,10 +93,15 @@ export * from "./contract.js";
92
93
  export const mcp = definePlugin({
93
94
  name: "mcp",
94
95
  requires: ["chat", "spaces", "contacts"],
95
- collections: { mcp_receipt: receipt, mcp_rate: rate, mcp_closed: closed },
96
+ collections: {
97
+ mcp_receipt: receipt,
98
+ mcp_rate: rate,
99
+ mcp_closed: closed,
100
+ mcp_opening: opening,
101
+ },
96
102
  actions: { "mcp.call": callAction, "mcp.prune": pruneAction },
97
103
  processors: { "mcp.forgotten": forgottenProcessor, "mcp.erased": erasedProcessor },
98
- // What's past goes: counters, receipts.
104
+ // What's past goes: counters, receipts, openings.
99
105
  schedules: { "mcp.prune": { every: "10m", call: "mcp.prune", input: {} } },
100
106
  // Which tools a contact is offered, as each tool's `offer` says.
101
107
  views: { "mcp:offered": { mcp: offeredView } },
@@ -3,7 +3,7 @@ import { type Session } from "./layout.js";
3
3
  export declare function connect(url: string, trace?: (sql: string) => void): Promise<Session & {
4
4
  end(): Promise<void>;
5
5
  }>;
6
- /** Refuses raw SQL on a server whose store names no maintenance role. */
6
+ /** Refuses raw SQL on a server whose store names no role for it. */
7
7
  export declare const noRole: () => Error & {
8
8
  code: string;
9
9
  public?: true;
@@ -14,6 +14,13 @@ export declare const noRole: () => Error & {
14
14
  * the allowlist.
15
15
  */
16
16
  export declare function allowed(db: Session, schema: string): Promise<void>;
17
+ /**
18
+ * Refuses maintenance SQL as the store's own role (`storeRole`) when that
19
+ * role, on `db`, could turn SQL into server commands or file access
20
+ * (`UNCONFINED`). Whatever else the role may do, the key may too: that's
21
+ * what the store's options chose.
22
+ */
23
+ export declare function confined(db: Session): Promise<void>;
17
24
  /**
18
25
  * PGlite's check, its one session being the store's: no other schema's
19
26
  * tables within reach (another store's, in this process), and no remote
@@ -10,12 +10,18 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
10
10
  * Maintenance SQL's connection to a PostgreSQL server, and the role it runs
11
11
  * as (runtime/maintain.ts; the store's `inspect` and `execute`).
12
12
  *
13
- * - **A role of its own, required on a server**
13
+ * - **A role of its own, by default required on a server**
14
14
  * (`postgresStore({ maintenance: { url } })`): the store's own role owns
15
15
  * the tables, may stop the app's connections, and is whatever the
16
16
  * deployment made it (a superuser, even). Without one, raw SQL is
17
17
  * refused; the collections' operations, named queries and blobs don't
18
18
  * need it. PGlite, in this process, runs it as its one session.
19
+ * - **Or, deliberately, the store's own role**
20
+ * (`postgresStore({ maintenance: { storeRole: true } })`): the key's
21
+ * holder may then do whatever that role may (drop its tables, read every
22
+ * schema it reaches). Only the allowlist below is skipped, which that role
23
+ * couldn't pass; `confined` still refuses one that would turn SQL into
24
+ * server commands or file access.
19
25
  * - **Exactly the grants maintenance needs, checked before every
20
26
  * statement** (`allowed`), on the connection that runs it: an allowlist,
21
27
  * not a list of what's refused. The role has no attribute beyond LOGIN,
@@ -28,10 +34,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
28
34
  * function (one runs as its owner: revoke EXECUTE from PUBLIC), and the
29
35
  * database has no `dblink` or `postgres_fdw`. The store makes no
30
36
  * triggers: one on its tables means someone else did, and nothing runs.
31
- * - **A connection of its own for each statement, closed after:** whatever
32
- * the statement leaves on its session goes with it. It speaks `pg`
33
- * itself, the driver Ominipg loads, so every query goes over the
34
- * extended protocol, where the server refuses more than one statement.
37
+ * - **A connection of its own for each statement, closed after,** as
38
+ * either role: whatever the statement leaves on its session goes with
39
+ * it. It speaks `pg` itself, the driver Ominipg loads, so every query
40
+ * goes over the extended protocol, where the server refuses more than
41
+ * one statement.
35
42
  * - **At most `connections` at once** (2 by default; ../shared/capped.ts).
36
43
  */
37
44
  import { failure } from "../../../runtime/errors.js";
@@ -65,10 +72,12 @@ export async function connect(url, trace) {
65
72
  };
66
73
  }
67
74
  const unsafe = (message) => failure("unsafe_role", message);
68
- /** Refuses raw SQL on a server whose store names no maintenance role. */
69
- export const noRole = () => unsafe("Raw SQL on a PostgreSQL server runs only as a maintenance role of its own: " +
70
- "postgresStore({ maintenance: { url } }), set up as the README's Maintenance says. " +
71
- "The collections' operations, named queries and blobs work without it.");
75
+ /** Refuses raw SQL on a server whose store names no role for it. */
76
+ export const noRole = () => unsafe("Raw SQL on a PostgreSQL server runs as a maintenance role of its own, " +
77
+ "postgresStore({ maintenance: { url } }), set up as the README's Maintenance says; or, " +
78
+ "deliberately, as the store's own role, postgresStore({ maintenance: { storeRole: true } }), " +
79
+ "which lets the key do whatever that role may (the README says what that costs). " +
80
+ "The collections' operations, named queries and blobs work without either.");
72
81
  /**
73
82
  * Cloud SQL's markers of an IAM database user (a role made by `gcloud sql
74
83
  * users create … --type=cloud_iam_*`): such a role is a member of one. Every
@@ -235,6 +244,64 @@ export async function allowed(db, schema) {
235
244
  throw unsafe(`The maintenance role holds more than maintenance needs: it ${shown}. It must hold the ` +
236
245
  `README's grants on "${schema}" and nothing else.`);
237
246
  }
247
+ /** The predefined roles whose members PostgreSQL lets run server programs or reach its files. */
248
+ const SERVER = ["pg_execute_server_program", "pg_read_server_files", "pg_write_server_files"];
249
+ /**
250
+ * What the session's role (`session_user`) may do that turns SQL into
251
+ * server commands or file access, one line for each, none when nothing:
252
+ * being a superuser, or able to become one (a member of a superuser role
253
+ * could `set_config('role', …)` to it within a statement); being a member,
254
+ * by any path, of a role in `$1`; before PostgreSQL 16, `CREATEROLE`
255
+ * (enough to grant itself any of them, and a function it made could use
256
+ * one within the same statement, before the check after it); and running
257
+ * a function that reads or writes the server's files (`pg_read_file`,
258
+ * `lo_import`, `lo_export`…, refused to everyone unless granted). Cloud
259
+ * SQL's `postgres` user isn't a superuser (a member of
260
+ * `cloudsqlsuperuser`, which isn't one either), and from PostgreSQL 16 its
261
+ * `CREATEROLE` grants nothing it doesn't administer. Every catalog name is
262
+ * `pg_catalog`'s.
263
+ */
264
+ const UNCONFINED = `
265
+ WITH me AS (
266
+ SELECT oid, rolsuper, rolcreaterole FROM pg_catalog.pg_roles WHERE rolname = session_user
267
+ )
268
+ SELECT problem FROM (
269
+ SELECT 1 AS n, 'is a superuser' AS problem FROM me WHERE rolsuper
270
+ UNION ALL SELECT 2, 'may become superuser ' || r.rolname::pg_catalog.text ||
271
+ ' (it is a member of it)'
272
+ FROM pg_catalog.pg_roles r, me
273
+ WHERE NOT me.rolsuper AND r.rolsuper AND r.oid <> me.oid
274
+ AND pg_catalog.pg_has_role(me.oid, r.oid, 'MEMBER')
275
+ UNION ALL SELECT 3, 'is a member of ' || r.rolname::pg_catalog.text
276
+ FROM pg_catalog.pg_roles r, me
277
+ WHERE NOT me.rolsuper AND r.rolname::pg_catalog.text = ANY ($1::pg_catalog.text[])
278
+ AND pg_catalog.pg_has_role(me.oid, r.oid, 'MEMBER')
279
+ UNION ALL SELECT 4, 'may create roles (CREATEROLE), and before PostgreSQL 16 so grant itself ' ||
280
+ 'any of them'
281
+ FROM me WHERE NOT me.rolsuper AND me.rolcreaterole
282
+ AND pg_catalog.current_setting('server_version_num')::pg_catalog.int4 < 160000
283
+ UNION ALL SELECT 5, 'may run ' || p.oid::pg_catalog.regprocedure::pg_catalog.text
284
+ FROM pg_catalog.pg_proc p, me
285
+ WHERE NOT me.rolsuper AND p.pronamespace = 'pg_catalog'::pg_catalog.regnamespace
286
+ AND p.proname IN ('pg_read_file', 'pg_read_binary_file', 'lo_import', 'lo_export',
287
+ 'pg_file_write', 'pg_file_rename', 'pg_file_unlink')
288
+ AND pg_catalog.has_function_privilege(me.oid, p.oid, 'EXECUTE')
289
+ ) found ORDER BY n, problem`;
290
+ /**
291
+ * Refuses maintenance SQL as the store's own role (`storeRole`) when that
292
+ * role, on `db`, could turn SQL into server commands or file access
293
+ * (`UNCONFINED`). Whatever else the role may do, the key may too: that's
294
+ * what the store's options chose.
295
+ */
296
+ export async function confined(db) {
297
+ const problems = (await db.query(UNCONFINED, [SERVER])).rows.map((row) => row.problem);
298
+ if (!problems.length)
299
+ return;
300
+ throw unsafe(`Raw SQL as the store's own role (storeRole) could run commands on the database server or ` +
301
+ `reach its files: the role ${problems.join("; ")}. Use a store role that can't (Cloud ` +
302
+ `SQL's postgres user can't, from PostgreSQL 16), or a maintenance role of its own ` +
303
+ `(maintenance: { url }).`);
304
+ }
238
305
  /**
239
306
  * PGlite's check, its one session being the store's: no other schema's
240
307
  * tables within reach (another store's, in this process), and no remote
@@ -37,13 +37,21 @@ export declare function postgresStore(options: {
37
37
  /** Hears every SQL statement sent, for debugging. */
38
38
  trace?: (sql: string) => void;
39
39
  /**
40
- * Where maintenance SQL connects (`inspect`, a transaction's `execute`;
41
- * see maintenance.ts): a role of its own, holding exactly maintenance's
42
- * grants on this schema. A new connection for each statement, closed
43
- * after, `connections` at most at once (2). On a server, raw SQL needs it.
40
+ * Who maintenance SQL runs as (`inspect`, a transaction's `execute`; see
41
+ * maintenance.ts), on a server, where raw SQL needs one or the other:
42
+ * `url`, a role of its own, holding exactly maintenance's grants on this
43
+ * schema; or, deliberately, `storeRole: true`, the store's own role (this
44
+ * store's `url`, or its pool's), so the key may do whatever that role may,
45
+ * dropping its tables included. Not both. Either way a new connection for
46
+ * each statement, closed after, `connections` at most at once (2).
44
47
  */
45
48
  maintenance?: {
46
49
  url: string;
50
+ storeRole?: never;
51
+ connections?: number;
52
+ } | {
53
+ storeRole: true;
54
+ url?: never;
47
55
  connections?: number;
48
56
  };
49
57
  }): Promise<Store & {
@@ -11,7 +11,7 @@ import { constant, forget, ident, others, prepare, remembered, TABLES, } from ".
11
11
  import { postgresPool } from "./pool.js";
12
12
  import { dropTenant } from "./tenants.js";
13
13
  import { statement } from "../shared/statement.js";
14
- import { allowed, alone, connect, noRole, triggers } from "./maintenance.js";
14
+ import { allowed, alone, confined, connect, noRole, triggers } from "./maintenance.js";
15
15
  import { connections } from "../shared/capped.js";
16
16
  import { upTo, weight } from "../shared/rows.js";
17
17
  export { postgresPool } from "./pool.js";
@@ -91,6 +91,11 @@ const unique = (events) => {
91
91
  export async function postgresStore(options) {
92
92
  if (!options.url === !options.pool)
93
93
  throw new Error("postgresStore takes a url or a pool");
94
+ const storeRole = options.maintenance?.storeRole === true;
95
+ if (storeRole && options.maintenance?.url !== undefined) {
96
+ throw new Error("postgresStore's maintenance runs as a role of its own (url) or as the store's own role " +
97
+ "(storeRole: true), not both");
98
+ }
94
99
  const tenant = options.tenant ?? "";
95
100
  if (tenant.includes("\u0000"))
96
101
  throw new Error("A tenant can't contain a NUL character");
@@ -124,6 +129,12 @@ export async function postgresStore(options) {
124
129
  * temporary object last, whatever the statement set (in its transaction).
125
130
  */
126
131
  const settled = "SELECT pg_catalog.set_config('search_path', 'pg_catalog, pg_temp', true)";
132
+ /**
133
+ * The role check on a server, on the connection maintenance SQL runs on:
134
+ * a role of its own holds exactly maintenance's grants; the store's own
135
+ * role can't run server commands or reach its files (maintenance.ts).
136
+ */
137
+ const checked = (db) => storeRole ? confined(db) : allowed(db, schema);
127
138
  let layout;
128
139
  try {
129
140
  layout = await prepare(pool, schema);
@@ -569,7 +580,7 @@ export async function postgresStore(options) {
569
580
  throw triggered();
570
581
  // What the role holds is as it was: no large object, setting or grant came of it.
571
582
  if (pool.server)
572
- await allowed(counted(tx), schema);
583
+ await checked(counted(tx));
573
584
  // Events it wrote into the log keep their numbers: this commit's go after them.
574
585
  if (last !== undefined)
575
586
  last = Math.max(last, Number(after.seq));
@@ -918,27 +929,29 @@ export async function postgresStore(options) {
918
929
  /**
919
930
  * Refuses maintenance SQL where it could reach what isn't this tenant's: a
920
931
  * schema other tenants share; on a server, a role that holds anything
921
- * beyond maintenance's grants; in PGlite, another schema's tables
922
- * (maintenance.ts). `db` is the connection it runs on.
932
+ * beyond maintenance's grants, or as the store's own role, one that could
933
+ * run server commands or reach its files; in PGlite, another schema's
934
+ * tables (maintenance.ts). `db` is the connection it runs on.
923
935
  */
924
936
  const reachable = async (db) => {
925
937
  if (pool.server)
926
- return await allowed(db, schema);
938
+ return await checked(db);
927
939
  if (await others(counted(committed), schema, tenant))
928
940
  throw sharedSchema();
929
941
  await alone(db, schema);
930
942
  };
931
943
  /**
932
944
  * On a server, a connection of its own for one maintenance statement, as
933
- * the maintenance role, closed after, within the cap (maintenance.ts).
945
+ * the maintenance role (or the store's own), closed after, within the cap
946
+ * (maintenance.ts).
934
947
  */
935
948
  const dedicated = async (work) => {
936
949
  // A schema other tenants share comes first: no role would make SQL there theirs alone.
937
950
  if (await others(counted(committed), schema, tenant))
938
951
  throw sharedSchema();
939
- if (!options.maintenance)
952
+ const url = storeRole ? pool.url : options.maintenance?.url;
953
+ if (!url)
940
954
  throw noRole();
941
- const url = options.maintenance.url;
942
955
  return await capped(async () => {
943
956
  const db = await connect(url);
944
957
  try {