@fungi.computer/oyster 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -12
- package/dist/agents.d.ts +66 -22
- package/dist/agents.js +128 -38
- package/dist/app-builds.d.ts +2 -0
- package/dist/app-builds.js +17 -6
- package/dist/authorization.d.ts +25 -3
- package/dist/authorization.js +47 -14
- package/dist/browser/capability-source.d.ts +23 -5
- package/dist/browser/capability-source.js +19 -22
- package/dist/browser/index.d.ts +2 -1
- package/dist/browser/index.js +1 -0
- package/dist/browser/live-view.d.ts +38 -0
- package/dist/browser/live-view.js +179 -0
- package/dist/build/artifact-writer.d.ts +11 -2
- package/dist/build/artifact-writer.js +42 -24
- package/dist/build/candidate-cli.mjs +26 -18
- package/dist/build/content-objects.d.ts +29 -14
- package/dist/build/content-objects.js +57 -19
- package/dist/build/local-build.js +3 -0
- package/dist/build/submission-contract.d.ts +1 -1
- package/dist/build/submission-contract.js +5 -5
- package/dist/build-egress.d.ts +8 -7
- package/dist/build-egress.js +4 -3
- package/dist/build.d.ts +1 -1
- package/dist/channels/binding.d.ts +2 -0
- package/dist/channels/run-decision.d.ts +33 -0
- package/dist/channels/run-decision.js +25 -0
- package/dist/channels/visitor-channel.d.ts +84 -14
- package/dist/channels/visitor-channel.js +55 -32
- package/dist/channels/visitor-edge.d.ts +18 -2
- package/dist/channels/visitor-edge.js +67 -5
- package/dist/channels/visitors.d.ts +4 -0
- package/dist/channels/visitors.js +22 -1
- package/dist/channels/web-binding.d.ts +117 -0
- package/dist/channels/web-binding.js +227 -0
- package/dist/embed-metafiles.d.ts +8 -0
- package/dist/embed-metafiles.js +2 -0
- package/dist/embed-scripts.d.ts +8 -0
- package/dist/embed-scripts.js +3 -0
- package/dist/host.d.ts +3 -1
- package/dist/host.js +6 -1
- package/dist/install-release-cli.d.ts +2 -1
- package/dist/install-release-cli.js +18 -10
- package/dist/installation-client.d.ts +1 -0
- package/dist/installation-operations.d.ts +2 -0
- package/dist/installation-operations.js +1 -0
- package/dist/pack.d.ts +5 -2
- package/dist/pack.js +3 -1
- package/dist/page/embed-challenge.d.ts +19 -0
- package/dist/page/embed-challenge.js +45 -0
- package/dist/page/embed-error.d.ts +2 -0
- package/dist/page/embed-error.js +16 -0
- package/dist/page/embed-loader-protocol.d.ts +12 -0
- package/dist/page/embed-loader-protocol.js +29 -0
- package/dist/standalone/agent-connections.d.ts +22 -19
- package/dist/standalone/agent-connections.js +150 -106
- package/dist/standalone/agents.d.ts +174 -16
- package/dist/standalone/agents.js +331 -21
- package/dist/standalone/browser.d.ts +14 -2
- package/dist/standalone/browser.js +52 -4
- package/dist/standalone/channel-session-door.d.ts +4 -0
- package/dist/standalone/channel-session-door.js +72 -0
- package/dist/standalone/computer-egress.d.ts +5 -3
- package/dist/standalone/computer-egress.js +1 -1
- package/dist/standalone/hello-app.d.ts +9 -0
- package/dist/standalone/hello-app.js +78 -0
- package/dist/standalone/install-apps-cli.d.ts +2 -1
- package/dist/standalone/install-apps-cli.js +36 -14
- package/dist/standalone/instance.js +2 -2
- package/dist/standalone/local-desktop.d.ts +11 -0
- package/dist/standalone/local-desktop.js +75 -0
- package/dist/standalone/owner-routes.d.ts +4 -3
- package/dist/standalone/owner-routes.js +7 -1
- package/dist/standalone/registry.d.ts +2 -0
- package/dist/standalone/sign-in-link.d.ts +9 -0
- package/dist/standalone/sign-in-link.js +49 -0
- package/dist/standalone/try-cli.d.ts +52 -0
- package/dist/standalone/try-cli.js +404 -0
- package/dist/standalone/visitor-edge.d.ts +36 -0
- package/dist/standalone/visitor-edge.js +67 -0
- package/dist/standalone/visitor-proof.d.ts +23 -0
- package/dist/standalone/visitor-proof.js +67 -0
- package/dist/standalone/website-channels.d.ts +134 -0
- package/dist/standalone/website-channels.js +262 -0
- package/dist/standalone/worker-routes.d.ts +4 -1
- package/dist/standalone/worker-routes.js +3 -0
- package/dist/standalone/worker.d.ts +2 -1
- package/dist/standalone/worker.js +5 -1
- package/dist/testing/capabilities.d.ts +3 -0
- package/dist/testing/capabilities.js +1 -0
- package/dist/testing/installation.d.ts +4 -2
- package/dist/testing/installation.js +7 -2
- package/dist/webhook-abuse.d.ts +7 -1
- package/dist/webhook-abuse.js +8 -2
- package/dist/workers-git.js +2 -2
- package/dist/workers.d.ts +7 -2
- package/dist/workers.js +1 -1
- package/docs/api/agents.md +103 -36
- package/docs/api/authorization.md +56 -11
- package/docs/api/browser.md +115 -8
- package/docs/api/build-contract.md +52 -10
- package/docs/api/build.md +16 -2
- package/docs/api/host.md +1 -0
- package/docs/api/pack.md +179 -3
- package/docs/api/workers-git.md +6 -6
- package/docs/site/agent-quickstart.mdx +8 -0
- package/package.json +34 -8
|
@@ -0,0 +1,404 @@
|
|
|
1
|
+
// `oyster try`: one command from nothing to a running local Oyster with a
|
|
2
|
+
// Hello App. It scaffolds a small project (the standalone worker and wrangler
|
|
3
|
+
// config this package ships, plus a package.json), installs it with the
|
|
4
|
+
// caller's package manager, runs `wrangler dev` locally, installs the Hello
|
|
5
|
+
// App and opens the browser. Running it again in the same directory restarts
|
|
6
|
+
// the server without scaffolding again.
|
|
7
|
+
//
|
|
8
|
+
// npx @fungi.computer/oyster try [directory] [--port 8787] [--no-open] [--verbose]
|
|
9
|
+
//
|
|
10
|
+
// Output goes through Lantern, the shared Fungi terminal kit: a wordmark, one
|
|
11
|
+
// spinner per real step, a success box and a next step for every failure. It
|
|
12
|
+
// is quiet by default; install and server output go to files under .oyster/
|
|
13
|
+
// and --verbose streams them instead. Piped output or CI gets plain lines.
|
|
14
|
+
import { spawn, spawnSync } from "node:child_process";
|
|
15
|
+
import { randomBytes } from "node:crypto";
|
|
16
|
+
import { createWriteStream } from "node:fs";
|
|
17
|
+
import { copyFile, mkdir, readdir, readFile, stat, writeFile, } from "node:fs/promises";
|
|
18
|
+
import { createServer } from "node:net";
|
|
19
|
+
import { basename, delimiter, join, resolve } from "node:path";
|
|
20
|
+
import process from "node:process";
|
|
21
|
+
import { parseArgs } from "node:util";
|
|
22
|
+
import { Cli } from "@fungi.computer/lantern";
|
|
23
|
+
import * as z from "zod";
|
|
24
|
+
import { installHelloApp } from "./hello-app.js";
|
|
25
|
+
import { installLocalDesktop, isInstalled } from "./local-desktop.js";
|
|
26
|
+
import { startSignInLink } from "./sign-in-link.js";
|
|
27
|
+
export const tryUsage = "Usage: oyster try [directory] [--port 8787] [--no-open] [--verbose] [--package <npm spec>]";
|
|
28
|
+
const tryHelp = `${tryUsage}
|
|
29
|
+
|
|
30
|
+
Creates ./my-oyster (or <directory>) with a local Oyster, installs it, starts it
|
|
31
|
+
on http://127.0.0.1:<port> and installs a Hello App from <directory>/hello-app,
|
|
32
|
+
a git repository you can edit. Commit an edit and run this again, from inside
|
|
33
|
+
that directory or by naming it, to restart and reinstall without scaffolding.
|
|
34
|
+
Press Ctrl-C to stop.
|
|
35
|
+
|
|
36
|
+
Options:
|
|
37
|
+
--port <number> port to listen on (default 8787)
|
|
38
|
+
--no-open do not open the browser
|
|
39
|
+
--verbose stream install and server output instead of saving it
|
|
40
|
+
under .oyster/
|
|
41
|
+
--package <spec> install Oyster from this npm spec instead of the version
|
|
42
|
+
that is running (a tarball path, for example)
|
|
43
|
+
-h, --help show this help
|
|
44
|
+
`;
|
|
45
|
+
// The local workspace builder (src/build/local-build.ts) refuses any other pnpm.
|
|
46
|
+
const localBuildPnpmVersion = "11.24.0";
|
|
47
|
+
const requiredNodeMajor = 24;
|
|
48
|
+
const ownerKeyFile = ".oyster-owner";
|
|
49
|
+
const logFile = join(".oyster", "wrangler.log");
|
|
50
|
+
const installLogFile = join(".oyster", "install.log");
|
|
51
|
+
const command = "npx @fungi.computer/oyster try";
|
|
52
|
+
/** A failure that knows the exact next step; the command shows both. */
|
|
53
|
+
class TryError extends Error {
|
|
54
|
+
title;
|
|
55
|
+
next;
|
|
56
|
+
constructor(title, next) {
|
|
57
|
+
super(`${title} ${next}`);
|
|
58
|
+
this.name = "TryError";
|
|
59
|
+
this.title = title;
|
|
60
|
+
this.next = next;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Streaming logs and a redrawing spinner cannot share a terminal, so
|
|
65
|
+
* --verbose prints plain lines instead of spinners.
|
|
66
|
+
*/
|
|
67
|
+
export function createTryCli(args) {
|
|
68
|
+
return args.includes("--verbose")
|
|
69
|
+
? new Cli({ brand: "fungi", interactive: false })
|
|
70
|
+
: new Cli({ brand: "fungi" });
|
|
71
|
+
}
|
|
72
|
+
/** Show a failed `oyster try` as an error with its next step. */
|
|
73
|
+
export function reportTryFailure(cause, ui) {
|
|
74
|
+
if (cause instanceof TryError)
|
|
75
|
+
ui.problem(cause.title, cause.next);
|
|
76
|
+
else
|
|
77
|
+
ui.problem(cause instanceof Error ? cause.message : String(cause), `Run \`${command} --help\` for the options, or add --verbose to see the full output.`);
|
|
78
|
+
}
|
|
79
|
+
const ownManifestSchema = z.object({
|
|
80
|
+
version: z.string(),
|
|
81
|
+
dependencies: z.record(z.string(), z.string()).default({}),
|
|
82
|
+
peerDependencies: z.record(z.string(), z.string()).default({}),
|
|
83
|
+
});
|
|
84
|
+
/** pnpm when it ran this command (`pnpm dlx`), otherwise npm. */
|
|
85
|
+
export function detectManager(userAgent) {
|
|
86
|
+
return userAgent?.startsWith("pnpm/") === true ? "pnpm" : "npm";
|
|
87
|
+
}
|
|
88
|
+
async function ownManifest() {
|
|
89
|
+
return ownManifestSchema.parse(JSON.parse(await readFile(join(import.meta.dirname, "../../package.json"), "utf8")));
|
|
90
|
+
}
|
|
91
|
+
function projectManifest(own, spec) {
|
|
92
|
+
const dependencies = {
|
|
93
|
+
"@fungi.computer/oyster": spec ?? own.version,
|
|
94
|
+
"@fungi.computer/computer": own.dependencies["@fungi.computer/computer"] ?? "latest",
|
|
95
|
+
react: "^19.2.0",
|
|
96
|
+
"react-dom": "^19.2.0",
|
|
97
|
+
// Building the desktop here needs this exact pnpm, whatever the caller uses.
|
|
98
|
+
pnpm: localBuildPnpmVersion,
|
|
99
|
+
wrangler: own.peerDependencies.wrangler ?? "^4.127.1",
|
|
100
|
+
};
|
|
101
|
+
return (JSON.stringify({
|
|
102
|
+
name: "my-oyster",
|
|
103
|
+
private: true,
|
|
104
|
+
type: "module",
|
|
105
|
+
// npm 11.19 and newer skip dependency install scripts unless approved.
|
|
106
|
+
allowScripts: {
|
|
107
|
+
"@google/genai": false,
|
|
108
|
+
"@mongodb-js/zstd": false,
|
|
109
|
+
esbuild: true,
|
|
110
|
+
exifreader: false,
|
|
111
|
+
"node-liblzma": false,
|
|
112
|
+
protobufjs: false,
|
|
113
|
+
workerd: true,
|
|
114
|
+
},
|
|
115
|
+
scripts: { start: "npx @fungi.computer/oyster try" },
|
|
116
|
+
dependencies,
|
|
117
|
+
}, null, 2) + "\n");
|
|
118
|
+
}
|
|
119
|
+
// pnpm 11 refuses dependency build scripts it was not told about.
|
|
120
|
+
const pnpmWorkspace = `allowBuilds:
|
|
121
|
+
"@google/genai": false
|
|
122
|
+
"@mongodb-js/zstd": false
|
|
123
|
+
esbuild: true
|
|
124
|
+
exifreader: false
|
|
125
|
+
node-liblzma: false
|
|
126
|
+
protobufjs: false
|
|
127
|
+
workerd: true
|
|
128
|
+
`;
|
|
129
|
+
async function exists(path) {
|
|
130
|
+
return stat(path).then(() => true, () => false);
|
|
131
|
+
}
|
|
132
|
+
async function scaffold(directory, own, spec, manager) {
|
|
133
|
+
await mkdir(directory, { recursive: true });
|
|
134
|
+
const examples = join(import.meta.dirname, "../../examples/standalone");
|
|
135
|
+
for (const name of ["worker.ts", "wrangler.jsonc"])
|
|
136
|
+
await copyFile(join(examples, name), join(directory, name));
|
|
137
|
+
await writeFile(join(directory, "package.json"), projectManifest(own, spec));
|
|
138
|
+
if (manager === "pnpm")
|
|
139
|
+
await writeFile(join(directory, "pnpm-workspace.yaml"), pnpmWorkspace);
|
|
140
|
+
await writeFile(join(directory, ".gitignore"), ".oyster/\n.wrangler/\nnode_modules/\n.oyster-owner\n");
|
|
141
|
+
}
|
|
142
|
+
/** Write a child's output to a log file, and also to stderr when verbose. */
|
|
143
|
+
function captureOutput(child, log, verbose) {
|
|
144
|
+
for (const stream of [child.stdout, child.stderr]) {
|
|
145
|
+
stream?.pipe(log, { end: false });
|
|
146
|
+
if (verbose)
|
|
147
|
+
stream?.pipe(process.stderr, { end: false });
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
async function runInstall(directory, manager, verbose) {
|
|
151
|
+
await mkdir(join(directory, ".oyster"), { recursive: true });
|
|
152
|
+
const log = createWriteStream(join(directory, installLogFile));
|
|
153
|
+
try {
|
|
154
|
+
await new Promise((done, fail) => {
|
|
155
|
+
const child = spawn(manager, ["install"], {
|
|
156
|
+
cwd: directory,
|
|
157
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
158
|
+
shell: process.platform === "win32",
|
|
159
|
+
});
|
|
160
|
+
captureOutput(child, log, verbose);
|
|
161
|
+
child.on("error", (cause) => {
|
|
162
|
+
fail(new Error(`Could not run ${manager} install: ${cause.message}`));
|
|
163
|
+
});
|
|
164
|
+
child.on("close", (code) => {
|
|
165
|
+
if (code === 0)
|
|
166
|
+
done();
|
|
167
|
+
else
|
|
168
|
+
fail(new Error(`${manager} install failed (exit ${String(code)}).`));
|
|
169
|
+
});
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
finally {
|
|
173
|
+
log.end();
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
function portFree(port) {
|
|
177
|
+
return new Promise((done) => {
|
|
178
|
+
const server = createServer();
|
|
179
|
+
server.once("error", () => {
|
|
180
|
+
done(false);
|
|
181
|
+
});
|
|
182
|
+
server.listen(port, "127.0.0.1", () => {
|
|
183
|
+
server.close(() => {
|
|
184
|
+
done(true);
|
|
185
|
+
});
|
|
186
|
+
});
|
|
187
|
+
});
|
|
188
|
+
}
|
|
189
|
+
async function waitUntilReady(url, child, timeoutMs) {
|
|
190
|
+
const deadline = Date.now() + timeoutMs;
|
|
191
|
+
while (Date.now() < deadline) {
|
|
192
|
+
if (child.exitCode !== null)
|
|
193
|
+
return false;
|
|
194
|
+
const answered = await fetch(`${url}/login`, {
|
|
195
|
+
signal: AbortSignal.timeout(2_000),
|
|
196
|
+
}).then((response) => response.status < 500, () => false);
|
|
197
|
+
if (answered)
|
|
198
|
+
return true;
|
|
199
|
+
await new Promise((wake) => setTimeout(wake, 500));
|
|
200
|
+
}
|
|
201
|
+
return false;
|
|
202
|
+
}
|
|
203
|
+
async function tail(path) {
|
|
204
|
+
try {
|
|
205
|
+
const text = await readFile(path, "utf8");
|
|
206
|
+
return text.trim().split("\n").slice(-15).join("\n");
|
|
207
|
+
}
|
|
208
|
+
catch {
|
|
209
|
+
return "(no log was written)";
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
function startWrangler(input) {
|
|
213
|
+
return (async () => {
|
|
214
|
+
const wrangler = join(input.directory, "node_modules", "wrangler", "bin", "wrangler.js");
|
|
215
|
+
if (!(await exists(wrangler)))
|
|
216
|
+
throw new TryError(`wrangler is not installed in ${input.directory}.`, `Run \`npm install\` there, then run \`${command}\` again.`);
|
|
217
|
+
await mkdir(join(input.directory, ".oyster"), { recursive: true });
|
|
218
|
+
const log = join(input.directory, logFile);
|
|
219
|
+
const logStream = createWriteStream(log);
|
|
220
|
+
const url = `http://127.0.0.1:${String(input.port)}`;
|
|
221
|
+
const child = spawn(process.execPath, [
|
|
222
|
+
wrangler,
|
|
223
|
+
"dev",
|
|
224
|
+
"--local",
|
|
225
|
+
"--enable-containers=false",
|
|
226
|
+
"--ip",
|
|
227
|
+
"127.0.0.1",
|
|
228
|
+
"--port",
|
|
229
|
+
String(input.port),
|
|
230
|
+
"--local-upstream",
|
|
231
|
+
"oyster.test",
|
|
232
|
+
"--upstream-protocol",
|
|
233
|
+
"https",
|
|
234
|
+
"--var",
|
|
235
|
+
`OYSTER_OWNER_KEY:${input.key}`,
|
|
236
|
+
"--var",
|
|
237
|
+
"OYSTER_ORIGIN:https://oyster.test",
|
|
238
|
+
], {
|
|
239
|
+
cwd: input.directory,
|
|
240
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
241
|
+
env: { ...process.env, WRANGLER_SEND_METRICS: "false" },
|
|
242
|
+
});
|
|
243
|
+
captureOutput(child, logStream, input.verbose);
|
|
244
|
+
const exited = new Promise((done) => {
|
|
245
|
+
child.on("close", (code) => {
|
|
246
|
+
logStream.end();
|
|
247
|
+
done(code);
|
|
248
|
+
});
|
|
249
|
+
});
|
|
250
|
+
const stop = async () => {
|
|
251
|
+
if (child.exitCode === null)
|
|
252
|
+
child.kill("SIGTERM");
|
|
253
|
+
const forced = setTimeout(() => {
|
|
254
|
+
child.kill("SIGKILL");
|
|
255
|
+
}, 10_000);
|
|
256
|
+
await exited;
|
|
257
|
+
clearTimeout(forced);
|
|
258
|
+
};
|
|
259
|
+
if (!(await waitUntilReady(url, child, 120_000))) {
|
|
260
|
+
await stop();
|
|
261
|
+
throw new TryError("Oyster did not start.", `Read ${log}, or run \`${command} --verbose\` to watch it start. The last lines:\n${await tail(log)}`);
|
|
262
|
+
}
|
|
263
|
+
return { stop, exited };
|
|
264
|
+
})();
|
|
265
|
+
}
|
|
266
|
+
function openBrowser(url) {
|
|
267
|
+
const [command, args] = process.platform === "darwin"
|
|
268
|
+
? ["open", [url]]
|
|
269
|
+
: process.platform === "win32"
|
|
270
|
+
? ["cmd", ["/c", "start", "", url]]
|
|
271
|
+
: ["xdg-open", [url]];
|
|
272
|
+
const child = spawn(command, args, { stdio: "ignore", detached: true });
|
|
273
|
+
child.on("error", () => undefined);
|
|
274
|
+
child.unref();
|
|
275
|
+
}
|
|
276
|
+
function untilInterrupted() {
|
|
277
|
+
return new Promise((done) => {
|
|
278
|
+
const once = () => {
|
|
279
|
+
process.off("SIGINT", once);
|
|
280
|
+
process.off("SIGTERM", once);
|
|
281
|
+
done();
|
|
282
|
+
};
|
|
283
|
+
process.on("SIGINT", once);
|
|
284
|
+
process.on("SIGTERM", once);
|
|
285
|
+
});
|
|
286
|
+
}
|
|
287
|
+
const realEffects = {
|
|
288
|
+
installDependencies: runInstall,
|
|
289
|
+
startServer: startWrangler,
|
|
290
|
+
installHello: installHelloApp,
|
|
291
|
+
installDesktop: async ({ directory, ...input }) => {
|
|
292
|
+
process.env.PATH = `${join(directory, "node_modules", ".bin")}${delimiter}${process.env.PATH ?? ""}`;
|
|
293
|
+
if (!(await isInstalled({ ...input, installationId: "tourtois" })))
|
|
294
|
+
await installLocalDesktop(input);
|
|
295
|
+
},
|
|
296
|
+
signInLink: startSignInLink,
|
|
297
|
+
open: openBrowser,
|
|
298
|
+
interrupted: untilInterrupted,
|
|
299
|
+
portFree,
|
|
300
|
+
};
|
|
301
|
+
export async function tryOyster(args, effects = realEffects, ui = createTryCli(args)) {
|
|
302
|
+
const { values, positionals } = parseArgs({
|
|
303
|
+
args: [...args],
|
|
304
|
+
allowPositionals: true,
|
|
305
|
+
strict: true,
|
|
306
|
+
options: {
|
|
307
|
+
port: { type: "string" },
|
|
308
|
+
"no-open": { type: "boolean" },
|
|
309
|
+
verbose: { type: "boolean" },
|
|
310
|
+
package: { type: "string" },
|
|
311
|
+
help: { type: "boolean", short: "h" },
|
|
312
|
+
},
|
|
313
|
+
});
|
|
314
|
+
const verbose = values.verbose === true;
|
|
315
|
+
if (values.help === true) {
|
|
316
|
+
process.stdout.write(tryHelp);
|
|
317
|
+
return;
|
|
318
|
+
}
|
|
319
|
+
if (positionals.length > 1)
|
|
320
|
+
throw new Error(tryUsage);
|
|
321
|
+
ui.welcome("Oyster: your own Apps, running on this machine");
|
|
322
|
+
const major = Number(process.versions.node.split(".")[0]);
|
|
323
|
+
if (major < requiredNodeMajor)
|
|
324
|
+
throw new TryError(`Oyster needs Node ${String(requiredNodeMajor)} or newer; this is Node ${process.versions.node}.`, `Install a current Node from https://nodejs.org, then run \`${command}\` again.`);
|
|
325
|
+
if (!gitAvailable())
|
|
326
|
+
throw new TryError("Oyster builds the Hello App from a git commit, so it needs Git.", `Install Git from https://git-scm.com, then run \`${command}\` again.`);
|
|
327
|
+
const port = Number(values.port ?? "8787");
|
|
328
|
+
if (!Number.isInteger(port) || port < 1 || port > 65_535)
|
|
329
|
+
throw new TryError("--port must be a number from 1 to 65535.", `For example: \`${command} --port 8788\`.`);
|
|
330
|
+
const directory = resolve(positionals[0] ??
|
|
331
|
+
((await exists(join(process.cwd(), ownerKeyFile))) ? "." : "my-oyster"));
|
|
332
|
+
const keyPath = join(directory, ownerKeyFile);
|
|
333
|
+
const fresh = !(await exists(keyPath));
|
|
334
|
+
if (fresh) {
|
|
335
|
+
const occupied = (await exists(directory))
|
|
336
|
+
? (await readdir(directory)).length > 0
|
|
337
|
+
: false;
|
|
338
|
+
if (occupied)
|
|
339
|
+
throw new TryError(`${directory} already has files and is not an Oyster made by \`oyster try\`.`, `Choose a new directory: \`${command} <directory>\`.`);
|
|
340
|
+
}
|
|
341
|
+
if (!(await effects.portFree(port)))
|
|
342
|
+
throw new TryError(`Port ${String(port)} on 127.0.0.1 is already in use.`, `Stop whatever is using it, or choose another port: \`${command} --port ${String(port + 1)}\`.`);
|
|
343
|
+
let key;
|
|
344
|
+
if (fresh) {
|
|
345
|
+
const manager = detectManager(process.env.npm_config_user_agent);
|
|
346
|
+
const own = await ownManifest();
|
|
347
|
+
await ui.task(`Creating ${basename(directory)}`, () => scaffold(directory, own, values.package, manager));
|
|
348
|
+
await ui
|
|
349
|
+
.task(`Installing dependencies with ${manager} (a minute or two)`, () => effects.installDependencies(directory, manager, verbose))
|
|
350
|
+
.catch((cause) => {
|
|
351
|
+
throw new TryError(cause instanceof Error ? cause.message : String(cause), `Read ${join(directory, installLogFile)} (or add --verbose), delete ${directory}, and run \`${command}\` again.`);
|
|
352
|
+
});
|
|
353
|
+
key = Array.from(randomBytes(24), (byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
354
|
+
await writeFile(keyPath, key + "\n", { mode: 0o600 });
|
|
355
|
+
}
|
|
356
|
+
else {
|
|
357
|
+
key = (await readFile(keyPath, "utf8")).trim();
|
|
358
|
+
ui.info(`Restarting the Oyster in ${directory}`);
|
|
359
|
+
}
|
|
360
|
+
const url = `http://127.0.0.1:${String(port)}`;
|
|
361
|
+
const server = await ui.task("Starting Oyster", () => effects.startServer({ directory, port, key, verbose }));
|
|
362
|
+
let closeLink = () => undefined;
|
|
363
|
+
try {
|
|
364
|
+
await ui.task("Installing the Hello App", () => effects.installHello({ directory, url, key }));
|
|
365
|
+
await ui
|
|
366
|
+
.task(fresh
|
|
367
|
+
? "Building Tourtois (about 2 min the first time)"
|
|
368
|
+
: "Checking Tourtois", () => effects.installDesktop({ directory, url, key }))
|
|
369
|
+
.catch((cause) => {
|
|
370
|
+
ui.warn(`Tourtois, the desktop, could not be built (${cause instanceof Error ? cause.message : String(cause)}). Continuing with the Hello App.`, `Connect to the internet and run \`${command}\` again from ${directory} to try the desktop again.`);
|
|
371
|
+
});
|
|
372
|
+
const link = await ui.task("Opening your desktop", async () => {
|
|
373
|
+
const made = await effects.signInLink({ oysterUrl: url, key });
|
|
374
|
+
closeLink = made.close;
|
|
375
|
+
if (values["no-open"] !== true && process.stdout.isTTY)
|
|
376
|
+
effects.open(made.url);
|
|
377
|
+
return made;
|
|
378
|
+
});
|
|
379
|
+
ui.note("Oyster is running", [
|
|
380
|
+
`Open (works once): ${link.url}`,
|
|
381
|
+
`Oyster: ${url}`,
|
|
382
|
+
`Owner key saved in: ${keyPath}`,
|
|
383
|
+
`Hello App source: ${join(directory, "hello-app")}`,
|
|
384
|
+
`Sign in later by pasting that key at ${url}/login.`,
|
|
385
|
+
"Press Ctrl-C to stop.",
|
|
386
|
+
]);
|
|
387
|
+
const outcome = await Promise.race([
|
|
388
|
+
effects.interrupted().then(() => "interrupted"),
|
|
389
|
+
server.exited.then(() => "exited"),
|
|
390
|
+
]);
|
|
391
|
+
if (outcome === "exited")
|
|
392
|
+
throw new TryError("Oyster stopped unexpectedly.", `Read ${join(directory, logFile)}, then run \`${command}\` again.`);
|
|
393
|
+
}
|
|
394
|
+
finally {
|
|
395
|
+
closeLink();
|
|
396
|
+
ui.step("Stopping Oyster");
|
|
397
|
+
await server.stop();
|
|
398
|
+
}
|
|
399
|
+
ui.outro("Stopped. Run the same command again to start it again.");
|
|
400
|
+
}
|
|
401
|
+
/** Whether `git` is available; Hello App packing reads its commit. */
|
|
402
|
+
function gitAvailable() {
|
|
403
|
+
return spawnSync("git", ["--version"], { stdio: "ignore" }).status === 0;
|
|
404
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { Context, Env as HonoEnv } from "hono";
|
|
2
|
+
import type { ConversationBinding } from "../channels/binding.js";
|
|
3
|
+
import { type EdgeVerifiedVisitor, type VisitorSiteFacts, type VisitorTurnstile } from "../channels/visitor-edge.js";
|
|
4
|
+
import type { AuthenticatedChannelVisitor } from "../channels/visitor-channel.js";
|
|
5
|
+
import type { ChannelVisitors } from "../channels/visitors.js";
|
|
6
|
+
import type { StandaloneAgentBase } from "./agents.js";
|
|
7
|
+
/** The central owner keeps every binding's visitor families and address caps.
|
|
8
|
+
* A Durable Object can supply these four RPCs; no token store lives in Agents. */
|
|
9
|
+
export type StandaloneVisitorIdentity = Pick<ChannelVisitors, "mint" | "refresh" | "rotate" | "authenticate">;
|
|
10
|
+
export type StandaloneVisitorAgent = Pick<StandaloneAgentBase, "sendChannelVisitor" | "withdrawChannelVisitor" | "latestPendingChannelVisitor" | "openChannelVisitor" | "watchChannelVisitor">;
|
|
11
|
+
/** A web binding and the Agent it puts in front of visitors. */
|
|
12
|
+
export type StandaloneVisitorBinding = ConversationBinding & Readonly<{
|
|
13
|
+
agentId: string;
|
|
14
|
+
}>;
|
|
15
|
+
/** A resolved site: the binding the edge enforces and the chrome it serves. */
|
|
16
|
+
export type StandaloneVisitorSite = Readonly<{
|
|
17
|
+
binding: StandaloneVisitorBinding;
|
|
18
|
+
facts: VisitorSiteFacts;
|
|
19
|
+
}>;
|
|
20
|
+
/**
|
|
21
|
+
* Web sites with central identity and one dedicated Agent per site. The host
|
|
22
|
+
* supplies the address salt, the site lookup and the Agent; the edge
|
|
23
|
+
* authenticates before selecting an Agent and never sends a bearer into it.
|
|
24
|
+
*/
|
|
25
|
+
export declare function standaloneVisitorEdge<E extends HonoEnv>(host: {
|
|
26
|
+
/** Re-read on every request and stream beat; suspension never freezes. */
|
|
27
|
+
site: (context: Context<E>, siteKey: string) => StandaloneVisitorSite | null | Promise<StandaloneVisitorSite | null>;
|
|
28
|
+
visitors: (context: Context<E>) => StandaloneVisitorIdentity;
|
|
29
|
+
agent: (context: Context<E>, binding: StandaloneVisitorBinding, visitor: EdgeVerifiedVisitor<AuthenticatedChannelVisitor>) => StandaloneVisitorAgent | Promise<StandaloneVisitorAgent>;
|
|
30
|
+
/** Private host secret shared with the Agent subclass, never the browser. */
|
|
31
|
+
proofKey: (context: Context<E>) => string;
|
|
32
|
+
addressHash: (context: Context<E>) => Promise<string>;
|
|
33
|
+
turnstile: (context: Context<E>) => VisitorTurnstile;
|
|
34
|
+
assetPath: (kind: "widget" | "styles") => string;
|
|
35
|
+
onError: (error: Error, context: Context<E>) => Response | Promise<Response>;
|
|
36
|
+
}): import("hono").Hono<E, import("hono/types").BlankSchema, "/">;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { createVisitorEdge, } from "../channels/visitor-edge.js";
|
|
2
|
+
import { proveVisitor } from "./visitor-proof.js";
|
|
3
|
+
/**
|
|
4
|
+
* Web sites with central identity and one dedicated Agent per site. The host
|
|
5
|
+
* supplies the address salt, the site lookup and the Agent; the edge
|
|
6
|
+
* authenticates before selecting an Agent and never sends a bearer into it.
|
|
7
|
+
*/
|
|
8
|
+
export function standaloneVisitorEdge(host) {
|
|
9
|
+
const identityDoor = (context, site) => ({
|
|
10
|
+
[Symbol.dispose]: () => undefined,
|
|
11
|
+
readChannelSite: ({ bindingId, siteKey: key }) => Promise.resolve(bindingId === site.bindingId &&
|
|
12
|
+
site.binding.selector.provider === "web" &&
|
|
13
|
+
key === site.binding.selector.siteKey &&
|
|
14
|
+
site.binding.lifecycle === "active"
|
|
15
|
+
? site.facts
|
|
16
|
+
: null),
|
|
17
|
+
mintChannelVisitor: ({ siteKey: key, addressHash }) => host.visitors(context).mint(site.binding, key, addressHash),
|
|
18
|
+
refreshChannelVisitor: ({ refreshSecret }) => host.visitors(context).refresh(site.binding, refreshSecret),
|
|
19
|
+
rotateChannelVisitor: ({ siteKey: key, accessToken, addressHash }) => host
|
|
20
|
+
.visitors(context)
|
|
21
|
+
.rotate(site.binding, key, accessToken, addressHash),
|
|
22
|
+
sendAsChannelVisitor: () => Promise.resolve({ kind: "unauthorized" }),
|
|
23
|
+
withdrawAsChannelVisitor: () => Promise.resolve({ kind: "unauthorized" }),
|
|
24
|
+
latestPendingAsChannelVisitor: () => Promise.resolve({ kind: "unauthorized" }),
|
|
25
|
+
openVisitorSession: () => Promise.resolve({ kind: "unauthorized" }),
|
|
26
|
+
watchAsChannelVisitor: () => Promise.resolve({ kind: "unauthorized" }),
|
|
27
|
+
// The old GET /conversation has no standalone caller. Do not invent an
|
|
28
|
+
// unauthenticated site-wide transcript for a per-visitor Agent directory.
|
|
29
|
+
readAsChannelVisitor: () => Promise.resolve({ kind: "unauthorized" }),
|
|
30
|
+
});
|
|
31
|
+
return createVisitorEdge({
|
|
32
|
+
resolveSite: async (context, key) => {
|
|
33
|
+
const resolved = await host.site(context, key);
|
|
34
|
+
if (resolved === null)
|
|
35
|
+
return null;
|
|
36
|
+
const { binding, facts } = resolved;
|
|
37
|
+
return binding.selector.provider === "web" &&
|
|
38
|
+
binding.selector.siteKey === key
|
|
39
|
+
? { bindingId: binding.bindingId, binding, facts }
|
|
40
|
+
: null;
|
|
41
|
+
},
|
|
42
|
+
openSite: (context, site) => Promise.resolve(identityDoor(context, site)),
|
|
43
|
+
authenticateVisitor: (context, site, token) => host.visitors(context).authenticate(site.bindingId, token),
|
|
44
|
+
openChannel: async (context, site, visitor) => {
|
|
45
|
+
const proven = await proveVisitor(site.bindingId, visitor, host.proofKey(context));
|
|
46
|
+
const agent = await host.agent(context, site.binding, visitor);
|
|
47
|
+
const identity = identityDoor(context, site);
|
|
48
|
+
return {
|
|
49
|
+
[Symbol.dispose]: () => undefined,
|
|
50
|
+
readChannelSite: identity.readChannelSite,
|
|
51
|
+
mintChannelVisitor: identity.mintChannelVisitor,
|
|
52
|
+
refreshChannelVisitor: identity.refreshChannelVisitor,
|
|
53
|
+
rotateChannelVisitor: identity.rotateChannelVisitor,
|
|
54
|
+
readAsChannelVisitor: identity.readAsChannelVisitor,
|
|
55
|
+
sendAsChannelVisitor: ({ requestId, text }) => agent.sendChannelVisitor(site.bindingId, proven, requestId, text),
|
|
56
|
+
withdrawAsChannelVisitor: ({ requestId }) => agent.withdrawChannelVisitor(site.bindingId, proven, requestId),
|
|
57
|
+
latestPendingAsChannelVisitor: () => agent.latestPendingChannelVisitor(site.bindingId, proven),
|
|
58
|
+
openVisitorSession: ({ options }) => agent.openChannelVisitor(site.bindingId, proven, options),
|
|
59
|
+
watchAsChannelVisitor: () => agent.watchChannelVisitor(site.bindingId, proven),
|
|
60
|
+
};
|
|
61
|
+
},
|
|
62
|
+
addressHash: host.addressHash,
|
|
63
|
+
turnstile: host.turnstile,
|
|
64
|
+
assetPath: host.assetPath,
|
|
65
|
+
onError: host.onError,
|
|
66
|
+
});
|
|
67
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import type { AuthenticatedChannelVisitor } from "../channels/visitor-channel.js";
|
|
3
|
+
import type { EdgeVerifiedVisitor } from "../channels/visitor-edge.js";
|
|
4
|
+
/** An internal, short-lived assertion, not the visitor's bearer. The Worker
|
|
5
|
+
* and its Agent owner receive the same host secret; no public route reads it.
|
|
6
|
+
* This is required because a TypeScript brand disappears over DO RPC. */
|
|
7
|
+
declare const proofSchema: z.ZodObject<{
|
|
8
|
+
visitorId: z.ZodString;
|
|
9
|
+
addressHash: z.ZodString;
|
|
10
|
+
bindingId: z.ZodString;
|
|
11
|
+
expiresAt: z.ZodNumber;
|
|
12
|
+
signature: z.ZodBase64URL;
|
|
13
|
+
}, z.core.$strict>;
|
|
14
|
+
export type ProvenVisitor = AuthenticatedChannelVisitor & Readonly<{
|
|
15
|
+
edgeProof: z.infer<typeof proofSchema>;
|
|
16
|
+
}>;
|
|
17
|
+
/** The edge calls this only after the central visitor owner authenticated
|
|
18
|
+
* this request. Neither bearer nor proof key crosses to the public client. */
|
|
19
|
+
export declare function proveVisitor(bindingId: string, visitor: EdgeVerifiedVisitor<AuthenticatedChannelVisitor>, secret: string, now?: number): Promise<ProvenVisitor>;
|
|
20
|
+
/** Every public Agent RPC must verify before accessing a conversation or
|
|
21
|
+
* running a model. A forged or stale identity cannot cross the DO boundary. */
|
|
22
|
+
export declare function verifyVisitor(bindingId: string, value: unknown, secret: string | null, now?: number): Promise<ProvenVisitor>;
|
|
23
|
+
export {};
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/** An internal, short-lived assertion, not the visitor's bearer. The Worker
|
|
3
|
+
* and its Agent owner receive the same host secret; no public route reads it.
|
|
4
|
+
* This is required because a TypeScript brand disappears over DO RPC. */
|
|
5
|
+
const proofSchema = z.strictObject({
|
|
6
|
+
visitorId: z.string().min(1).max(160),
|
|
7
|
+
addressHash: z.string().min(1).max(160),
|
|
8
|
+
bindingId: z.string().min(1).max(160),
|
|
9
|
+
expiresAt: z.number().int().nonnegative(),
|
|
10
|
+
signature: z.base64url().length(43),
|
|
11
|
+
});
|
|
12
|
+
const encoder = new TextEncoder();
|
|
13
|
+
const maxAge = 30_000;
|
|
14
|
+
const input = (proof) => JSON.stringify([
|
|
15
|
+
"oyster:website-visitor:v1",
|
|
16
|
+
proof.bindingId,
|
|
17
|
+
proof.visitorId,
|
|
18
|
+
proof.addressHash,
|
|
19
|
+
proof.expiresAt,
|
|
20
|
+
]);
|
|
21
|
+
async function keyFor(secret) {
|
|
22
|
+
if (encoder.encode(secret).length < 32)
|
|
23
|
+
throw new Error("Website channel proof key is unavailable");
|
|
24
|
+
return crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
|
|
25
|
+
}
|
|
26
|
+
/** The edge calls this only after the central visitor owner authenticated
|
|
27
|
+
* this request. Neither bearer nor proof key crosses to the public client. */
|
|
28
|
+
export async function proveVisitor(bindingId, visitor, secret, now = Date.now()) {
|
|
29
|
+
const fields = {
|
|
30
|
+
bindingId,
|
|
31
|
+
visitorId: visitor.visitorId,
|
|
32
|
+
addressHash: visitor.addressHash,
|
|
33
|
+
expiresAt: now + maxAge,
|
|
34
|
+
};
|
|
35
|
+
const bytes = new Uint8Array(await crypto.subtle.sign("HMAC", await keyFor(secret), encoder.encode(input(fields))));
|
|
36
|
+
const signature = btoa(String.fromCharCode(...bytes))
|
|
37
|
+
.replaceAll("+", "-")
|
|
38
|
+
.replaceAll("/", "_")
|
|
39
|
+
.replace(/=+$/u, "");
|
|
40
|
+
return { ...visitor, edgeProof: { ...fields, signature } };
|
|
41
|
+
}
|
|
42
|
+
/** Every public Agent RPC must verify before accessing a conversation or
|
|
43
|
+
* running a model. A forged or stale identity cannot cross the DO boundary. */
|
|
44
|
+
export async function verifyVisitor(bindingId, value, secret, now = Date.now()) {
|
|
45
|
+
const visitor = z
|
|
46
|
+
.strictObject({
|
|
47
|
+
visitorId: z.string().min(1).max(160),
|
|
48
|
+
addressHash: z.string().min(1).max(160),
|
|
49
|
+
expiresAt: z.number().int().nonnegative(),
|
|
50
|
+
edgeProof: proofSchema,
|
|
51
|
+
})
|
|
52
|
+
.safeParse(value);
|
|
53
|
+
if (!visitor.success ||
|
|
54
|
+
secret === null ||
|
|
55
|
+
visitor.data.edgeProof.bindingId !== bindingId ||
|
|
56
|
+
visitor.data.edgeProof.visitorId !== visitor.data.visitorId ||
|
|
57
|
+
visitor.data.edgeProof.addressHash !== visitor.data.addressHash ||
|
|
58
|
+
visitor.data.expiresAt < now ||
|
|
59
|
+
visitor.data.edgeProof.expiresAt < now ||
|
|
60
|
+
visitor.data.edgeProof.expiresAt > now + maxAge)
|
|
61
|
+
throw new Error("Website channel identity is unauthorized");
|
|
62
|
+
const { signature, ...fields } = visitor.data.edgeProof;
|
|
63
|
+
const bytes = Uint8Array.from(atob(signature.replaceAll("-", "+").replaceAll("_", "/") + "="), (char) => char.charCodeAt(0));
|
|
64
|
+
if (!(await crypto.subtle.verify("HMAC", await keyFor(secret), bytes, encoder.encode(input(fields)))))
|
|
65
|
+
throw new Error("Website channel identity is unauthorized");
|
|
66
|
+
return visitor.data;
|
|
67
|
+
}
|