copilotz 1.0.0-rc.21 → 1.0.0-rc.23

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.
Files changed (211) hide show
  1. package/CHANGELOG.md +320 -1
  2. package/README.md +217 -87
  3. package/hosts/orgs/mod.d.ts +33 -13
  4. package/hosts/orgs/mod.js +183 -84
  5. package/hosts/web/address.d.ts +11 -0
  6. package/hosts/web/address.js +46 -0
  7. package/hosts/web/assets.js +11 -5
  8. package/hosts/web/entrances.d.ts +250 -0
  9. package/hosts/web/entrances.js +362 -0
  10. package/hosts/web/host.d.ts +15 -3
  11. package/hosts/web/host.js +31 -18
  12. package/hosts/web/mod.d.ts +4 -2
  13. package/hosts/web/mod.js +6 -0
  14. package/hosts/web/node/bundle.d.ts +5 -0
  15. package/hosts/web/node/bundle.js +1 -1
  16. package/hosts/web/node/mod.d.ts +6 -4
  17. package/hosts/web/node/mod.js +6 -4
  18. package/hosts/web/node/serve.d.ts +20 -23
  19. package/hosts/web/node/serve.js +10 -21
  20. package/hosts/web/routes.d.ts +23 -17
  21. package/hosts/web/routes.js +56 -32
  22. package/hosts/web/server.d.ts +89 -44
  23. package/hosts/web/server.js +208 -108
  24. package/hosts/web/signin.d.ts +7 -10
  25. package/hosts/web/signin.js +6 -3
  26. package/hosts/web/surface.d.ts +20 -0
  27. package/hosts/web/surface.js +42 -0
  28. package/hosts/web/theme/css.d.ts +2 -1
  29. package/hosts/web/theme/css.js +9 -2
  30. package/hosts/web/tickets.d.ts +14 -1
  31. package/hosts/web/tickets.js +30 -7
  32. package/hosts/web/widget.d.ts +31 -0
  33. package/hosts/web/widget.js +429 -0
  34. package/hosts/web/widgets.d.ts +43 -0
  35. package/hosts/web/widgets.js +117 -0
  36. package/package.json +5 -1
  37. package/plugins/access/contacts/actions/forget.js +3 -1
  38. package/plugins/access/contacts/actions/start.js +18 -8
  39. package/plugins/access/contacts/collections/contact.d.ts +2 -2
  40. package/plugins/access/contacts/collections/contact.js +1 -1
  41. package/plugins/access/contacts/contract.d.ts +5 -5
  42. package/plugins/access/contacts/contract.js +5 -5
  43. package/plugins/access/contacts/mod.d.ts +4 -0
  44. package/plugins/access/contacts/mod.js +4 -0
  45. package/plugins/access/contacts/views/contact.js +1 -0
  46. package/plugins/access/dev/actions/sign-in.d.ts +1 -0
  47. package/plugins/access/dev/actions/sign-in.js +38 -0
  48. package/plugins/access/dev/mod.d.ts +17 -0
  49. package/plugins/access/dev/mod.js +31 -0
  50. package/plugins/access/dev/shared/nearby.d.ts +2 -0
  51. package/plugins/access/dev/shared/nearby.js +27 -0
  52. package/plugins/access/directory/actions/invite.js +2 -2
  53. package/plugins/access/directory/actions/org.js +11 -8
  54. package/plugins/access/directory/collections/credit-code.d.ts +1 -1
  55. package/plugins/access/google/actions/sign-in.js +2 -0
  56. package/plugins/access/google/mod.d.ts +4 -2
  57. package/plugins/access/google/mod.js +15 -2
  58. package/plugins/access/identity/actions/session.js +5 -3
  59. package/plugins/access/identity/mod.d.ts +4 -2
  60. package/plugins/access/identity/mod.js +17 -2
  61. package/plugins/access/mod.d.ts +7 -0
  62. package/plugins/access/mod.js +1 -0
  63. package/plugins/access/spaces/shared/declared.d.ts +1 -1
  64. package/plugins/access/spaces/shared/rules.d.ts +16 -5
  65. package/plugins/access/spaces/shared/rules.js +74 -6
  66. package/plugins/agents/chat/actions/send.d.ts +21 -0
  67. package/plugins/agents/chat/actions/send.js +72 -13
  68. package/plugins/agents/chat/collections/file.d.ts +15 -0
  69. package/plugins/agents/chat/collections/file.js +12 -3
  70. package/plugins/agents/chat/collections/live.d.ts +11 -0
  71. package/plugins/agents/chat/collections/live.js +11 -1
  72. package/plugins/agents/chat/collections/message.d.ts +1 -1
  73. package/plugins/agents/chat/collections/wait.d.ts +1 -1
  74. package/plugins/agents/chat/contract.d.ts +3 -2
  75. package/plugins/agents/chat/contract.js +1 -0
  76. package/plugins/agents/chat/mod.d.ts +9 -3
  77. package/plugins/agents/chat/mod.js +28 -7
  78. package/plugins/agents/chat/processors/failed.js +8 -3
  79. package/plugins/agents/chat/processors/turn.js +6 -3
  80. package/plugins/agents/chat/shared/agents.js +11 -2
  81. package/plugins/agents/chat/shared/live.d.ts +4 -2
  82. package/plugins/agents/chat/shared/live.js +2 -1
  83. package/plugins/agents/chat/shared/types.d.ts +8 -0
  84. package/plugins/agents/history/collections/outline.d.ts +2 -2
  85. package/plugins/agents/openapi/shared/files.js +2 -0
  86. package/plugins/agents/routines/collections/routine.d.ts +1 -1
  87. package/plugins/billing/credits/collections/plan.d.ts +2 -2
  88. package/plugins/billing/credits/collections/room.d.ts +1 -1
  89. package/plugins/billing/usage/collections/rollup.d.ts +2 -2
  90. package/plugins/billing/usage/collections/usage.d.ts +2 -2
  91. package/plugins/compute/cloud/actions/pool.js +2 -0
  92. package/plugins/compute/cloud/actions/remote.js +4 -2
  93. package/plugins/compute/cloud/actions/vms.js +2 -0
  94. package/plugins/compute/cloud/collections/pool-vm.d.ts +1 -1
  95. package/plugins/compute/computers/actions/admit.js +2 -0
  96. package/plugins/compute/computers/actions/code.js +2 -0
  97. package/plugins/compute/computers/actions/enrollment.js +2 -0
  98. package/plugins/compute/computers/actions/work.js +3 -0
  99. package/plugins/compute/computers/program/version.d.ts +1 -1
  100. package/plugins/compute/computers/program/version.js +1 -1
  101. package/plugins/compute/computers/resources/downloads.js +1 -1
  102. package/plugins/compute/computers/resources/previews.js +5 -2
  103. package/plugins/interfaces/maintenance/mod.d.ts +3 -1
  104. package/plugins/interfaces/maintenance/mod.js +3 -1
  105. package/plugins/interfaces/mcp/actions/call.d.ts +4 -0
  106. package/plugins/interfaces/mcp/actions/call.js +120 -18
  107. package/plugins/interfaces/mcp/actions/conversation.d.ts +1 -0
  108. package/plugins/interfaces/mcp/actions/conversation.js +49 -0
  109. package/plugins/interfaces/mcp/actions/prune.js +5 -3
  110. package/plugins/interfaces/mcp/collections/opening.d.ts +24 -0
  111. package/plugins/interfaces/mcp/collections/opening.js +28 -0
  112. package/plugins/interfaces/mcp/mod.d.ts +27 -3
  113. package/plugins/interfaces/mcp/mod.js +42 -7
  114. package/plugins/interfaces/mcp/resources/server.d.ts +13 -4
  115. package/plugins/interfaces/mcp/resources/server.js +163 -21
  116. package/plugins/interfaces/mcp/resources/tools.d.ts +88 -12
  117. package/plugins/interfaces/mcp/resources/tools.js +113 -19
  118. package/plugins/interfaces/mcp/resources/widgets.d.ts +161 -0
  119. package/plugins/interfaces/mcp/resources/widgets.js +246 -0
  120. package/plugins/interfaces/mcp/shared/keys.d.ts +25 -19
  121. package/plugins/interfaces/mcp/shared/keys.js +55 -9
  122. package/plugins/interfaces/mcp/shared/settings.d.ts +70 -37
  123. package/plugins/interfaces/mcp/shared/settings.js +64 -39
  124. package/plugins/interfaces/mcp/views/offered.d.ts +1 -1
  125. package/plugins/interfaces/mod.d.ts +2 -1
  126. package/plugins/interfaces/mod.js +2 -1
  127. package/plugins/interfaces/voice/collections/blocked.d.ts +2 -2
  128. package/plugins/interfaces/voice/collections/call.d.ts +3 -3
  129. package/plugins/interfaces/voice/contract.d.ts +1 -1
  130. package/plugins/interfaces/voice/mod.d.ts +3 -3
  131. package/plugins/interfaces/voice/mod.js +3 -3
  132. package/plugins/interfaces/voice/resources/relay.d.ts +5 -3
  133. package/plugins/interfaces/voice/resources/relay.js +17 -6
  134. package/plugins/interfaces/voice/resources/tools.js +2 -0
  135. package/plugins/interfaces/voice/shared/settings.d.ts +5 -0
  136. package/plugins/interfaces/voice/views/call.d.ts +18 -11
  137. package/plugins/interfaces/voice/views/call.js +15 -3
  138. package/plugins/interfaces/voice/views/message.d.ts +1 -1
  139. package/plugins/interfaces/web/actions/arrive.d.ts +1 -0
  140. package/plugins/interfaces/web/actions/arrive.js +120 -0
  141. package/plugins/interfaces/web/actions/prune.d.ts +1 -0
  142. package/plugins/interfaces/web/actions/prune.js +51 -0
  143. package/plugins/interfaces/web/actions/sending.d.ts +1 -0
  144. package/plugins/interfaces/web/actions/sending.js +222 -0
  145. package/plugins/interfaces/web/actions/spent.d.ts +2 -0
  146. package/plugins/interfaces/web/actions/spent.js +59 -0
  147. package/plugins/interfaces/web/collections/rate.d.ts +122 -0
  148. package/plugins/interfaces/web/collections/rate.js +37 -0
  149. package/plugins/interfaces/web/collections/visitor.d.ts +110 -0
  150. package/plugins/interfaces/web/collections/visitor.js +64 -0
  151. package/plugins/interfaces/web/contract.d.ts +4 -0
  152. package/plugins/interfaces/web/contract.js +1 -0
  153. package/plugins/interfaces/web/lines.d.ts +36 -0
  154. package/plugins/interfaces/web/lines.js +78 -0
  155. package/plugins/interfaces/web/processors/forget.d.ts +10 -0
  156. package/plugins/interfaces/web/processors/forget.js +14 -0
  157. package/plugins/interfaces/web/resources/entrance.d.ts +47 -0
  158. package/plugins/interfaces/web/resources/entrance.js +83 -0
  159. package/plugins/interfaces/web/resources/spend.d.ts +2 -0
  160. package/plugins/interfaces/web/resources/spend.js +62 -0
  161. package/plugins/interfaces/web/shared/budget.d.ts +65 -0
  162. package/plugins/interfaces/web/shared/budget.js +134 -0
  163. package/plugins/interfaces/web/shared/lines.d.ts +158 -0
  164. package/plugins/interfaces/web/shared/lines.js +156 -0
  165. package/plugins/interfaces/web/shared/secret.d.ts +33 -0
  166. package/plugins/interfaces/web/shared/secret.js +86 -0
  167. package/plugins/interfaces/whatsapp/collections/phone.d.ts +1 -1
  168. package/plugins/interfaces/whatsapp/mod.d.ts +1 -1
  169. package/plugins/interfaces/whatsapp/mod.js +1 -1
  170. package/plugins/interfaces/whatsapp/views/message.d.ts +1 -1
  171. package/plugins/models/contract.d.ts +1 -1
  172. package/plugins/models/shared/generate.js +13 -4
  173. package/plugins/models/shared/transcribe.js +7 -1
  174. package/plugins/models/shared/use.d.ts +16 -2
  175. package/plugins/models/shared/use.js +20 -0
  176. package/runtime/browsers.d.ts +153 -17
  177. package/runtime/browsers.js +336 -30
  178. package/runtime/cache.js +25 -5
  179. package/runtime/caller.d.ts +117 -0
  180. package/runtime/caller.js +215 -0
  181. package/runtime/client.d.ts +47 -3
  182. package/runtime/client.js +132 -42
  183. package/runtime/define.d.ts +30 -9
  184. package/runtime/executor.js +7 -6
  185. package/runtime/expiring.d.ts +23 -0
  186. package/runtime/expiring.js +64 -0
  187. package/runtime/links.d.ts +27 -4
  188. package/runtime/links.js +49 -11
  189. package/runtime/memory.js +102 -15
  190. package/runtime/mod.d.ts +3 -1
  191. package/runtime/mod.js +3 -1
  192. package/runtime/mongo.d.ts +12 -0
  193. package/runtime/mongo.js +44 -0
  194. package/runtime/observe.js +82 -9
  195. package/runtime/ops.d.ts +9 -1
  196. package/runtime/owner.d.ts +14 -1
  197. package/runtime/owner.js +78 -23
  198. package/runtime/reads.js +2 -2
  199. package/runtime/registry.js +9 -3
  200. package/runtime/runtime.d.ts +7 -0
  201. package/runtime/runtime.js +1 -0
  202. package/runtime/timers.js +2 -0
  203. package/runtime/views.d.ts +1 -1
  204. package/runtime/views.js +2 -2
  205. package/runtime/wire.d.ts +1 -1
  206. package/stores/sql/postgres/maintenance.d.ts +8 -1
  207. package/stores/sql/postgres/maintenance.js +76 -9
  208. package/stores/sql/postgres/mod.d.ts +12 -4
  209. package/stores/sql/postgres/mod.js +21 -8
  210. package/plugins/interfaces/mcp/shared/caller.d.ts +0 -45
  211. package/plugins/interfaces/mcp/shared/caller.js +0 -99
@@ -0,0 +1,250 @@
1
+ /**
2
+ * Who a browser is, and how people sign in, as the app's plugins declare
3
+ * them and the web host answers them. The host keeps every cookie: it reads
4
+ * them, sets them (httpOnly, so the page's code never sees them; `Secure`
5
+ * anywhere but over http to this machine or one on its network, as the host
6
+ * the request is for says: the front's word for it, see `siteOf`) and clears
7
+ * them; plugins see only the secret a cookie holds, and say who it is.
8
+ *
9
+ * - **Entrances** (the `entrances` resource, by name): each is a cookie and
10
+ * the query that says who its secret is (`{ secret }` in, an actor or null
11
+ * out, asked as the system). The identity plugin declares people's
12
+ * sessions (`session`); the web lines plugin, its visitors (`visitor`). A request is whoever the first entrance, in order, says it is.
13
+ * One may let a newcomer in (`arrive`): asked to connect without a cookie
14
+ * that's anyone (`POST /connect`), it makes them someone and gives the
15
+ * secret the host keeps in its cookie, or refuses (a limit), or passes.
16
+ * - **Sign-in** (the `signIn` resource, by name: `POST /signin/<name>`): an
17
+ * unrecorded Action (`record: false`: what it answers stays out of the
18
+ * log), called as the system with the request's JSON, that answers a
19
+ * person and a session; the host keeps the session in its entrance's
20
+ * cookie. Google sign-in declares `google`; dev sign-in, `dev` (this
21
+ * machine only: `local`, see `fromHere`). What the page's sign-in shows of
22
+ * each is its `page` (Google's client id, for its button).
23
+ * - **From the app's page only:** a browser says where a request comes from
24
+ * (`Origin`, `Sec-Fetch-Site`), and connecting, signing in and out from
25
+ * any other site is refused, so another site can't make its visitors
26
+ * arrive here, nor sign anyone in as someone else.
27
+ *
28
+ * ```ts
29
+ * resources: {
30
+ * entrances: { session: { cookie: "session", query: "credential.actor", end: "session.end" } },
31
+ * signIn: { google: { action: "google.sign-in", page: (r) => ({ clientId: r.google.clientId }) } },
32
+ * }
33
+ * ```
34
+ */
35
+ import type { Actor, Resources, Runtime } from "../../runtime/mod.js";
36
+ import { type Front } from "./routes.js";
37
+ /** One way a browser is someone: a cookie, and who its secret is. */
38
+ export type Entrance = {
39
+ /** The cookie it reads: letters, digits, `-` and `_`. */
40
+ cookie: string;
41
+ /** Who its secret is: a query (`<collection>.<query>`), given `{ secret }`, answering an actor or null. */
42
+ query: string;
43
+ /**
44
+ * A newcomer coming in, on `POST /connect` without a cookie that's anyone:
45
+ * who they are now, and the secret for the cookie (kept `days`, 30 unless
46
+ * said); nothing, to let the next entrance decide; or a refusal, thrown (a
47
+ * `failure`: `too_many` is a 429, its message said when it's public). It's
48
+ * given the request (its headers say who calls, as the app's front does)
49
+ * and what the page asked (`asked`: `/connect`'s JSON, `web({ arrive })`).
50
+ */
51
+ arrive?(request: Request, door: Door): Arrived | null | undefined | Promise<Arrived | null | undefined>;
52
+ /** Ends what its secret is, on `POST /signout`: an Action, called as its actor with `{ secret }`. */
53
+ end?: string;
54
+ /** Where it's asked among the others, lower first (0 unless said); then by name. */
55
+ order?: number;
56
+ /**
57
+ * The cookie's `SameSite`: `lax` (the default: it comes along when another
58
+ * site links here, as an OAuth provider's redirect does) or `strict` (only
59
+ * from the app's own pages).
60
+ */
61
+ sameSite?: "lax" | "strict";
62
+ /**
63
+ * Whether its cookie is this host's alone (unless `false`): named
64
+ * `__Host-<cookie>` wherever it's Secure, so no other host under the same
65
+ * domain (a preview's, a sibling app's) can set one in its place, to make
66
+ * a browser someone it chose. Over http to this machine or one on its
67
+ * network, where nothing's Secure, it's its plain name. `false` keeps the
68
+ * plain name everywhere, for a cookie something else under the domain
69
+ * reads too.
70
+ */
71
+ hostOnly?: boolean;
72
+ };
73
+ /** What an entrance letting someone in is given. */
74
+ export type Door = {
75
+ runtime: Runtime;
76
+ /** What the page asked for coming in (`/connect`'s JSON object; `{}` when none). */
77
+ asked: Record<string, unknown>;
78
+ /** The host the request is for, as the app's front says. */
79
+ host: string;
80
+ /**
81
+ * Where the request came from, as its socket says (see address.ts): the
82
+ * peer the listener saw, never a header. Undefined when nothing says.
83
+ */
84
+ address?: string;
85
+ /**
86
+ * The secret this entrance's cookie holds, when the request carries one
87
+ * that its query says is no one (yet): an entrance whose secrets stand on
88
+ * their own (signed, nothing kept) lets them back in as who they were.
89
+ */
90
+ secret?: string;
91
+ };
92
+ /** Someone let in: who, and the secret their cookie keeps, for `days` (30 unless said). */
93
+ export type Arrived = {
94
+ actor: Actor;
95
+ secret: string;
96
+ days?: number;
97
+ };
98
+ /** One way to sign in: `POST /signin/<name>`. */
99
+ export type SignIn = {
100
+ /**
101
+ * Signs someone in: an unrecorded Action (`record: false`), called as the
102
+ * system with the request's JSON; answers `{ person, session }`.
103
+ */
104
+ action: string;
105
+ /** From this machine only, to this machine (`fromHere`): for trying things out. */
106
+ local?: boolean;
107
+ /** What the page's sign-in shows of it (plain JSON), or a function of the app's resources. */
108
+ page?: Record<string, unknown> | ((resources: Resources) => Record<string, unknown> | undefined);
109
+ /** The entrance whose cookie keeps the session (`session` unless said). */
110
+ entrance?: string;
111
+ };
112
+ /** A cookie a request carries, by name. */
113
+ export declare const cookieOf: (request: Request, name: string) => string | undefined;
114
+ /** Whether a URL's host is this machine's own name: `localhost`, 127.0.0.0/8, `::1`. */
115
+ export declare const loopback: (url: URL) => boolean;
116
+ /**
117
+ * Whether a host name is this machine's or one on its network: loopback, a
118
+ * private or link-local address (10/8, 172.16/12, 192.168/16, 169.254/16,
119
+ * fc00::/7, fe80::/10), or a `.local` name. Plain http there is a LAN's.
120
+ */
121
+ export declare function nearby(hostname: string): boolean;
122
+ /** Whether a request says a proxy forwarded it (see `FORWARDING`). */
123
+ export declare const forwarded: (request: Request) => boolean;
124
+ /**
125
+ * Whether a request is this machine's, to this machine: the socket it came
126
+ * on is loopback (its client address, see address.ts), and so is the host
127
+ * it's for, as its URL says and as the front does, and nothing says a proxy
128
+ * forwarded it (`forwarded`): one on this machine reaches the app over
129
+ * loopback, and may rewrite `Host` to the app's own. No header makes it so
130
+ * (`Host: localhost` from elsewhere isn't), nor does a page another site
131
+ * served whose name now points here; a request whose address nobody set is
132
+ * from nowhere known, never here. A proxy that says nothing of whom it
133
+ * forwards for (nginx's `proxy_pass` as it comes) can't be told from this
134
+ * machine: dev sign-in refuses to start in an app with a public origin.
135
+ */
136
+ export declare function fromHere(request: Request, front?: Front): boolean;
137
+ /**
138
+ * The address a request is for, as its browser asked for it: its URL, on
139
+ * the host the front says when the front vouches for it (`hostOf`). What
140
+ * the host's cookies go by: a front's request is for a public host, though
141
+ * it reaches the app at a private address.
142
+ */
143
+ export declare function siteOf(request: Request, front?: Front): URL;
144
+ /**
145
+ * The name a cookie of the host's alone goes by, for a request to `site`
146
+ * (`siteOf`): `__Host-<name>` wherever it's Secure (no other host under the
147
+ * domain can set one), its plain name where nothing's Secure.
148
+ */
149
+ export declare const hostCookie: (site: URL, name: string) => string;
150
+ /**
151
+ * A cookie as the host sets it, for a request to `site` (`siteOf`):
152
+ * httpOnly, on the whole app, Secure unless this is plain http to this
153
+ * machine or one on its network. `maxAge` 0 clears it.
154
+ */
155
+ export declare const setCookie: (site: URL, value: string, maxAge: number, name: string, sameSite?: "lax" | "strict") => string;
156
+ /**
157
+ * Whether a request comes from the app's own page. A browser says where a
158
+ * request is from: `Sec-Fetch-Site`, and `Origin` (on every cross-site
159
+ * request, and every POST), which must be this host (as the app's front says
160
+ * it), over https anywhere but this machine or one on its network. Without
161
+ * either, it's not a browser's (or an old one's), and nothing a site does
162
+ * can send it.
163
+ */
164
+ export declare function fromPage(request: Request, front?: Front): boolean;
165
+ /** Whether a secret is one a cookie can keep as it is. */
166
+ export declare const cookieSafe: (secret: unknown) => secret is string;
167
+ /** A runtime's entrances, checked, in the order they're asked. */
168
+ export declare function entrancesOf(runtime: Runtime): (Entrance & {
169
+ name: string;
170
+ })[];
171
+ /**
172
+ * A runtime's ways to sign in, checked, by name. Each Action is unrecorded:
173
+ * what it answers is a session's secret, and what it's given may be one too
174
+ * (Google's ID token), so neither may be in the log.
175
+ */
176
+ export declare function signInsOf(runtime: Runtime, entrances: {
177
+ name: string;
178
+ }[]): Map<string, SignIn & {
179
+ entrance: string;
180
+ }>;
181
+ /** What the page's sign-in shows of each way to sign in, by name. */
182
+ export declare function signInPage(runtime: Runtime): Record<string, Record<string, unknown>>;
183
+ /** How a host reads who a request is. */
184
+ export type Whom = {
185
+ /** Who a request is, by the first entrance whose cookie is someone; null: nobody. */
186
+ (request: Request): Promise<Actor | null>;
187
+ entrances: (Entrance & {
188
+ name: string;
189
+ })[];
190
+ /** The address a request is for, as the front says (`siteOf`): what its cookies go by. */
191
+ site(request: Request): URL;
192
+ /** The name an entrance's cookie goes by here, for a request to `site`. */
193
+ named(entrance: Entrance, site: URL): string;
194
+ };
195
+ /**
196
+ * The plain name a cookie of the host's alone went by before it was one
197
+ * (`session`, for `__Host-session`): a browser signed in before still holds
198
+ * it. Undefined where the two are the same (plain http here, nothing Secure).
199
+ */
200
+ export declare const legacyName: (name: string) => string | undefined;
201
+ /**
202
+ * Retires what a request holds under a cookie's legacy name (`legacyName`
203
+ * of `current`): a secret still someone to `query` is ended first (`end`,
204
+ * called as them with `{ secret }`, as signing out does), so a host reading
205
+ * the plain name again (an older version, rolled back) finds no one there;
206
+ * then the cookie is cleared. Without `query`, it's only cleared (it held
207
+ * no secret). The `Set-Cookie` that clears it; none when there's nothing.
208
+ */
209
+ export declare function retire(runtime: Pick<Runtime, "call" | "query">, request: Request, site: URL, current: string, entrance?: {
210
+ query?: string;
211
+ end?: string;
212
+ sameSite?: "lax" | "strict";
213
+ }): Promise<string | undefined>;
214
+ /** Retires every entrance's legacy cookie a request holds (`retire`): the clearing `Set-Cookie`s. */
215
+ export declare function retireAll(runtime: Pick<Runtime, "call" | "query">, whom: Whom, request: Request): Promise<string[]>;
216
+ /**
217
+ * Who requests are, by a runtime's entrances. `cookie` names a declared
218
+ * cookie here (a host serving many orgs keeps each org's apart), and makes
219
+ * every cookie the host's alone (`hostCookie`), `hostOnly: false` too.
220
+ * `front` is the app's (see `siteOf`).
221
+ */
222
+ export declare function whomOf(runtime: Runtime, options?: {
223
+ cookie?: (name: string) => string;
224
+ front?: Front;
225
+ }): Whom;
226
+ /**
227
+ * Who an entrance's secret is, if anyone. A secret that isn't one a cookie
228
+ * could hold is no one, unasked; the query failing (the store away) throws,
229
+ * so a good cookie is never taken for a stale one and cleared.
230
+ */
231
+ export declare function recognise(runtime: Runtime, entrance: Entrance, secret: string | undefined): Promise<Actor | null>;
232
+ /** A request's JSON object (`{}` with no body); undefined when it's too large or not one. */
233
+ export declare function jsonOf(request: Request): Promise<Record<string, unknown> | undefined>;
234
+ /** An error as the host answers it: its code's status, its words only when they're for anyone. */
235
+ export declare function refusal(error: unknown, fallback: string): {
236
+ status: number;
237
+ error: string;
238
+ };
239
+ /**
240
+ * Coming in: who the request is, by its cookies; else, someone an entrance
241
+ * lets in now. The cookies to set go with it: a newcomer's, and a clearing
242
+ * for each cookie that turned out to be no one (forged, or ended).
243
+ */
244
+ export declare function arriving(runtime: Runtime, whom: Whom, request: Request, door: Door): Promise<{
245
+ actor: Actor;
246
+ cookies: string[];
247
+ } | {
248
+ actor: null;
249
+ cookies: string[];
250
+ }>;
@@ -0,0 +1,362 @@
1
+ import { clientAddress, loopbackAddress } from "./address.js";
2
+ import { bodyOf, hostOf } from "./routes.js";
3
+ /** A cookie a request carries, by name. */
4
+ export const cookieOf = (request, name) => request.headers.get("cookie")?.split(/;\s*/).find((c) => c.startsWith(`${name}=`))
5
+ ?.slice(name.length + 1);
6
+ /** Whether a URL's host is this machine's own name: `localhost`, 127.0.0.0/8, `::1`. */
7
+ export const loopback = (url) => loopbackName(url.hostname);
8
+ const loopbackName = (hostname) => hostname.toLowerCase() === "localhost" || loopbackAddress(hostname);
9
+ /**
10
+ * Whether a host name is this machine's or one on its network: loopback, a
11
+ * private or link-local address (10/8, 172.16/12, 192.168/16, 169.254/16,
12
+ * fc00::/7, fe80::/10), or a `.local` name. Plain http there is a LAN's.
13
+ */
14
+ export function nearby(hostname) {
15
+ const name = hostname.replace(/^\[|\]$/g, "").toLowerCase();
16
+ if (loopbackName(name) || name.endsWith(".local"))
17
+ return true;
18
+ const four = /^(\d{1,3})\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/.exec(name);
19
+ if (four) {
20
+ const [a, b] = [Number(four[1]), Number(four[2])];
21
+ return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) ||
22
+ (a === 169 && b === 254);
23
+ }
24
+ if (!name.includes(":"))
25
+ return false;
26
+ const first = parseInt(name.split(":")[0] || "0", 16);
27
+ return (first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80;
28
+ }
29
+ /**
30
+ * Headers a proxy adds to say whom it forwards for, or that it did:
31
+ * `forwarded`, `via`, any `x-forwarded-*`, the client-address headers
32
+ * fronts set (`x-real-ip`, `x-client-ip`, `x-cluster-client-ip`,
33
+ * `cf-connecting-ip`, `true-client-ip`, `fastly-client-ip`), Cloudflare's
34
+ * `cf-ray`, and the web host's own front's (`x-copilotz-front`).
35
+ */
36
+ const FORWARDING = /^(?:forwarded|via|x-forwarded-.+|x-real-ip|x-client-ip|x-cluster-client-ip|cf-connecting-ip|cf-ray|true-client-ip|fastly-client-ip|x-copilotz-front)$/;
37
+ /** Whether a request says a proxy forwarded it (see `FORWARDING`). */
38
+ export const forwarded = (request) => [...request.headers.keys()].some((name) => FORWARDING.test(name.toLowerCase()));
39
+ /**
40
+ * Whether a request is this machine's, to this machine: the socket it came
41
+ * on is loopback (its client address, see address.ts), and so is the host
42
+ * it's for, as its URL says and as the front does, and nothing says a proxy
43
+ * forwarded it (`forwarded`): one on this machine reaches the app over
44
+ * loopback, and may rewrite `Host` to the app's own. No header makes it so
45
+ * (`Host: localhost` from elsewhere isn't), nor does a page another site
46
+ * served whose name now points here; a request whose address nobody set is
47
+ * from nowhere known, never here. A proxy that says nothing of whom it
48
+ * forwards for (nginx's `proxy_pass` as it comes) can't be told from this
49
+ * machine: dev sign-in refuses to start in an app with a public origin.
50
+ */
51
+ export function fromHere(request, front) {
52
+ if (!loopbackAddress(clientAddress(request)))
53
+ return false;
54
+ if (forwarded(request))
55
+ return false;
56
+ if (!loopback(new URL(request.url)))
57
+ return false;
58
+ try {
59
+ return loopback(new URL(`http://${hostOf(request, front)}`));
60
+ }
61
+ catch {
62
+ return false;
63
+ }
64
+ }
65
+ /**
66
+ * The address a request is for, as its browser asked for it: its URL, on
67
+ * the host the front says when the front vouches for it (`hostOf`). What
68
+ * the host's cookies go by: a front's request is for a public host, though
69
+ * it reaches the app at a private address.
70
+ */
71
+ export function siteOf(request, front) {
72
+ const url = new URL(request.url);
73
+ const host = hostOf(request, front);
74
+ if (host === url.host)
75
+ return url;
76
+ try {
77
+ const said = new URL(`http://${host}`);
78
+ url.hostname = said.hostname;
79
+ url.port = said.port;
80
+ }
81
+ catch {
82
+ // Not a host at all: the front's word is no one's.
83
+ }
84
+ return url;
85
+ }
86
+ /**
87
+ * Whether the host's cookies are Secure, for a request to `site`
88
+ * (`siteOf`): anywhere but over http to this machine or one on its network,
89
+ * where a browser would drop them.
90
+ */
91
+ const secure = (site) => site.protocol === "https:" || !nearby(site.hostname);
92
+ /**
93
+ * The name a cookie of the host's alone goes by, for a request to `site`
94
+ * (`siteOf`): `__Host-<name>` wherever it's Secure (no other host under the
95
+ * domain can set one), its plain name where nothing's Secure.
96
+ */
97
+ export const hostCookie = (site, name) => `${secure(site) ? "__Host-" : ""}${name}`;
98
+ /**
99
+ * A cookie as the host sets it, for a request to `site` (`siteOf`):
100
+ * httpOnly, on the whole app, Secure unless this is plain http to this
101
+ * machine or one on its network. `maxAge` 0 clears it.
102
+ */
103
+ export const setCookie = (site, value, maxAge, name, sameSite = "lax") => `${name}=${value}; HttpOnly; SameSite=${sameSite === "strict" ? "Strict" : "Lax"}; Path=/; ` +
104
+ `Max-Age=${maxAge}${secure(site) ? "; Secure" : ""}`;
105
+ /**
106
+ * Whether a request comes from the app's own page. A browser says where a
107
+ * request is from: `Sec-Fetch-Site`, and `Origin` (on every cross-site
108
+ * request, and every POST), which must be this host (as the app's front says
109
+ * it), over https anywhere but this machine or one on its network. Without
110
+ * either, it's not a browser's (or an old one's), and nothing a site does
111
+ * can send it.
112
+ */
113
+ export function fromPage(request, front) {
114
+ const site = request.headers.get("sec-fetch-site");
115
+ if (site !== null && site !== "same-origin" && site !== "none")
116
+ return false;
117
+ const origin = request.headers.get("origin");
118
+ if (origin === null)
119
+ return true;
120
+ let from;
121
+ try {
122
+ from = new URL(origin);
123
+ }
124
+ catch {
125
+ return false;
126
+ }
127
+ if (from.origin !== origin)
128
+ return false;
129
+ if (from.protocol !== "https:" && !(from.protocol === "http:" && nearby(from.hostname))) {
130
+ return false;
131
+ }
132
+ return from.host === hostOf(request, front);
133
+ }
134
+ const NAME = /^[A-Za-z0-9_-]{1,64}$/;
135
+ /** What a cookie's value may be: plain characters, so it never ends the header. */
136
+ const SECRET = /^[A-Za-z0-9._~+/=-]{16,512}$/;
137
+ /** Whether a secret is one a cookie can keep as it is. */
138
+ export const cookieSafe = (secret) => typeof secret === "string" && SECRET.test(secret);
139
+ /** A runtime's entrances, checked, in the order they're asked. */
140
+ export function entrancesOf(runtime) {
141
+ const declared = (runtime.describe().resources.entrances ?? {});
142
+ const found = [];
143
+ const cookies = new Set();
144
+ for (const [name, entrance] of Object.entries(declared)) {
145
+ if (!entrance)
146
+ continue;
147
+ if (typeof entrance.cookie !== "string" || !NAME.test(entrance.cookie)) {
148
+ throw new Error(`entrances.${name}: its cookie is letters, digits, - and _`);
149
+ }
150
+ if (cookies.has(entrance.cookie)) {
151
+ throw new Error(`entrances.${name}: another entrance reads the cookie "${entrance.cookie}"`);
152
+ }
153
+ cookies.add(entrance.cookie);
154
+ if (typeof entrance.query !== "string" || !/^[\w-]+\.[\w-]+$/.test(entrance.query)) {
155
+ throw new Error(`entrances.${name}: its query is <collection>.<query>`);
156
+ }
157
+ if (entrance.arrive !== undefined && typeof entrance.arrive !== "function") {
158
+ throw new Error(`entrances.${name}: its arrive is a function`);
159
+ }
160
+ if (entrance.end !== undefined && typeof entrance.end !== "string") {
161
+ throw new Error(`entrances.${name}: its end is an Action's name`);
162
+ }
163
+ if (entrance.sameSite !== undefined && !["lax", "strict"].includes(entrance.sameSite)) {
164
+ throw new Error(`entrances.${name}: its sameSite is lax or strict`);
165
+ }
166
+ if (entrance.hostOnly !== undefined && typeof entrance.hostOnly !== "boolean") {
167
+ throw new Error(`entrances.${name}: its hostOnly is true or false`);
168
+ }
169
+ found.push({ ...entrance, name });
170
+ }
171
+ return found.sort((a, b) => (a.order ?? 0) - (b.order ?? 0) || (a.name < b.name ? -1 : 1));
172
+ }
173
+ /**
174
+ * A runtime's ways to sign in, checked, by name. Each Action is unrecorded:
175
+ * what it answers is a session's secret, and what it's given may be one too
176
+ * (Google's ID token), so neither may be in the log.
177
+ */
178
+ export function signInsOf(runtime, entrances) {
179
+ const described = runtime.describe();
180
+ const declared = (described.resources.signIn ?? {});
181
+ const found = new Map();
182
+ for (const [name, method] of Object.entries(declared)) {
183
+ if (!method)
184
+ continue;
185
+ if (!/^[a-z0-9-]{1,40}$/.test(name)) {
186
+ throw new Error(`signIn.${name}: its name is lowercase letters, digits and -`);
187
+ }
188
+ if (typeof method.action !== "string" || !method.action) {
189
+ throw new Error(`signIn.${name}: its action is an Action's name`);
190
+ }
191
+ const entrance = method.entrance ?? "session";
192
+ if (!entrances.some((e) => e.name === entrance)) {
193
+ throw new Error(`signIn.${name}: no entrance "${entrance}" keeps its session`);
194
+ }
195
+ const action = described.actions[method.action];
196
+ if (!action)
197
+ throw new Error(`signIn.${name}: no Action "${method.action}"`);
198
+ if (action.record !== false) {
199
+ throw new Error(`signIn.${name}: "${method.action}" is recorded, so the session it answers would be ` +
200
+ "in the log: make it record: false");
201
+ }
202
+ found.set(name, { ...method, entrance });
203
+ }
204
+ return found;
205
+ }
206
+ /** What the page's sign-in shows of each way to sign in, by name. */
207
+ export function signInPage(runtime) {
208
+ const resources = runtime.describe().resources;
209
+ const methods = signInsOf(runtime, entrancesOf(runtime));
210
+ return Object.fromEntries([...methods].flatMap(([name, method]) => {
211
+ const page = typeof method.page === "function" ? method.page(resources) : method.page ?? {};
212
+ return page ? [[name, page]] : [];
213
+ }));
214
+ }
215
+ /** Whether something an entrance answered is an actor. */
216
+ const actorish = (value) => !!value && typeof value === "object" &&
217
+ typeof value.kind === "string" && !!value.kind &&
218
+ typeof value.id === "string" && !!value.id;
219
+ /**
220
+ * The plain name a cookie of the host's alone went by before it was one
221
+ * (`session`, for `__Host-session`): a browser signed in before still holds
222
+ * it. Undefined where the two are the same (plain http here, nothing Secure).
223
+ */
224
+ export const legacyName = (name) => name.startsWith("__Host-") ? name.slice("__Host-".length) : undefined;
225
+ /**
226
+ * Retires what a request holds under a cookie's legacy name (`legacyName`
227
+ * of `current`): a secret still someone to `query` is ended first (`end`,
228
+ * called as them with `{ secret }`, as signing out does), so a host reading
229
+ * the plain name again (an older version, rolled back) finds no one there;
230
+ * then the cookie is cleared. Without `query`, it's only cleared (it held
231
+ * no secret). The `Set-Cookie` that clears it; none when there's nothing.
232
+ */
233
+ export async function retire(runtime, request, site, current, entrance = {}) {
234
+ const old = legacyName(current);
235
+ const secret = old ? cookieOf(request, old) : undefined;
236
+ if (!old || secret === undefined)
237
+ return undefined;
238
+ if (entrance.query && entrance.end && SECRET.test(secret)) {
239
+ const actor = await runtime.query(entrance.query, { secret }).catch(() => null);
240
+ if (actorish(actor)) {
241
+ await runtime.call(entrance.end, { secret }, { actor }).catch(() => { });
242
+ }
243
+ }
244
+ return setCookie(site, "", 0, old, entrance.sameSite);
245
+ }
246
+ /** Retires every entrance's legacy cookie a request holds (`retire`): the clearing `Set-Cookie`s. */
247
+ export async function retireAll(runtime, whom, request) {
248
+ const site = whom.site(request);
249
+ const cleared = await Promise.all(whom.entrances.map((entrance) => retire(runtime, request, site, whom.named(entrance, site), entrance)));
250
+ return cleared.filter((cookie) => cookie !== undefined);
251
+ }
252
+ /**
253
+ * Who requests are, by a runtime's entrances. `cookie` names a declared
254
+ * cookie here (a host serving many orgs keeps each org's apart), and makes
255
+ * every cookie the host's alone (`hostCookie`), `hostOnly: false` too.
256
+ * `front` is the app's (see `siteOf`).
257
+ */
258
+ export function whomOf(runtime, options = {}) {
259
+ const { cookie, front } = options;
260
+ const entrances = entrancesOf(runtime);
261
+ const site = (request) => siteOf(request, front);
262
+ const named = (entrance, at) => entrance.hostOnly !== false || cookie
263
+ ? hostCookie(at, cookie ? cookie(entrance.cookie) : entrance.cookie)
264
+ : entrance.cookie;
265
+ const whom = async (request) => {
266
+ const at = site(request);
267
+ for (const entrance of entrances) {
268
+ const actor = await recognise(runtime, entrance, cookieOf(request, named(entrance, at)));
269
+ if (actor)
270
+ return actor;
271
+ }
272
+ return null;
273
+ };
274
+ return Object.assign(whom, { entrances, site, named });
275
+ }
276
+ /**
277
+ * Who an entrance's secret is, if anyone. A secret that isn't one a cookie
278
+ * could hold is no one, unasked; the query failing (the store away) throws,
279
+ * so a good cookie is never taken for a stale one and cleared.
280
+ */
281
+ export async function recognise(runtime, entrance, secret) {
282
+ if (!secret || !SECRET.test(secret))
283
+ return null;
284
+ const actor = await runtime.query(entrance.query, { secret });
285
+ return actorish(actor) ? actor : null;
286
+ }
287
+ /** The most a JSON body to the host may be: a sign-in's token, what a page asks coming in. */
288
+ const BODY = 16_384;
289
+ /** A request's JSON object (`{}` with no body); undefined when it's too large or not one. */
290
+ export async function jsonOf(request) {
291
+ const bytes = await bodyOf(request, BODY);
292
+ if (!bytes)
293
+ return undefined;
294
+ if (!bytes.length)
295
+ return {};
296
+ try {
297
+ const parsed = JSON.parse(new TextDecoder().decode(bytes));
298
+ return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
299
+ }
300
+ catch {
301
+ return undefined;
302
+ }
303
+ }
304
+ /** A refusal's status, by its code. */
305
+ const STATUS = {
306
+ too_many: 429,
307
+ forbidden: 403,
308
+ invalid: 400,
309
+ not_found: 404,
310
+ unauthorized: 401,
311
+ };
312
+ /** An error as the host answers it: its code's status, its words only when they're for anyone. */
313
+ export function refusal(error, fallback) {
314
+ const { code, public: open } = (error ?? {});
315
+ const status = (code && STATUS[code]) || 500;
316
+ const said = open === true && error instanceof Error && error.message ? error.message : fallback;
317
+ if (status === 500)
318
+ console.error(`${fallback}:`, error instanceof Error ? error.message : error);
319
+ return { status, error: said.slice(0, 300) };
320
+ }
321
+ /**
322
+ * Coming in: who the request is, by its cookies; else, someone an entrance
323
+ * lets in now. The cookies to set go with it: a newcomer's, and a clearing
324
+ * for each cookie that turned out to be no one (forged, or ended).
325
+ */
326
+ export async function arriving(runtime, whom, request, door) {
327
+ const url = whom.site(request);
328
+ const stale = [];
329
+ for (const entrance of whom.entrances) {
330
+ const name = whom.named(entrance, url);
331
+ const secret = cookieOf(request, name);
332
+ if (secret === undefined)
333
+ continue;
334
+ const actor = await recognise(runtime, entrance, secret);
335
+ if (actor)
336
+ return { actor, cookies: [] };
337
+ stale.push({ name, secret, ...(entrance.sameSite ? { sameSite: entrance.sameSite } : {}) });
338
+ }
339
+ const clear = (except) => stale.filter((s) => s.name !== except).map((s) => setCookie(url, "", 0, s.name, s.sameSite));
340
+ for (const entrance of whom.entrances) {
341
+ if (!entrance.arrive)
342
+ continue;
343
+ // Its own cookie, held but no one to its query: the entrance may know it still (signed).
344
+ const held = stale.find((s) => s.name === whom.named(entrance, url))?.secret;
345
+ const arrived = await entrance.arrive(request, held && cookieSafe(held) ? { ...door, secret: held } : door);
346
+ if (!arrived)
347
+ continue;
348
+ if (!actorish(arrived.actor) || !cookieSafe(arrived.secret)) {
349
+ throw new Error(`entrances.${entrance.name}: arrive answered no actor, or a secret unfit for a cookie`);
350
+ }
351
+ const days = arrived.days ?? 30;
352
+ const name = whom.named(entrance, url);
353
+ return {
354
+ actor: arrived.actor,
355
+ cookies: [
356
+ ...clear(name),
357
+ setCookie(url, arrived.secret, Math.round(days * 86_400), name, entrance.sameSite),
358
+ ],
359
+ };
360
+ }
361
+ return { actor: null, cookies: clear() };
362
+ }
@@ -6,13 +6,25 @@ export type WebOptions = {
6
6
  /** The owner's socket (this page's origin, `/oxian`, by default). */
7
7
  url?: string;
8
8
  /**
9
- * The app's first steps once connected, as the person; what it returns
10
- * is where they work until the address says otherwise (`?in=`).
9
+ * What the page asks coming in, when the browser isn't anyone yet: `{
10
+ * line: "site" }` makes it a visitor of the app's web line `site` (the
11
+ * contacts plugin's). Someone signed in comes in as themselves.
11
12
  */
12
- start?(client: Client, person: string): Promise<{
13
+ arrive?: Record<string, unknown>;
14
+ /**
15
+ * The app's first steps once connected, as whoever the browser is (a
16
+ * person, a contact); what it returns is where they work until the
17
+ * address says otherwise (`?in=`).
18
+ */
19
+ start?(client: Client, actor: Who): Promise<{
13
20
  space?: string;
14
21
  } | void>;
15
22
  };
23
+ /** Who the browser is: a person (their id), or a web line's visitor (`contact`). */
24
+ export type Who = {
25
+ kind: string;
26
+ id: string;
27
+ };
16
28
  /**
17
29
  * What the shell is shown: the address, where the person works, and the
18
30
  * address's other parameters (`?tab=files`: `{ tab: "files" }`).