@fungi.computer/oyster 0.39.0 → 0.40.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/dist/auth.d.ts CHANGED
@@ -9,5 +9,7 @@ export declare const returningCookieName = "oyster_returning";
9
9
  * cookie holding the owner key's digest. The key is never stored in the browser.
10
10
  */
11
11
  export declare function ownerKeyAuth(ownerKey: string, ownerId?: string): OysterAuth;
12
+ /** How stale a key's last-used time may be: calls inside this window do not re-stamp it. */
13
+ export declare const lastUsedGranularityMs: number;
12
14
  /** The owner key, or a named key admitted as its canonical Team-key actor. */
13
- export declare function ownerOrKeyAuth(ownerKey: string, ownerId: string, keys: () => Pick<OysterKeyStore, "verify">): OysterAuth;
15
+ export declare function ownerOrKeyAuth(ownerKey: string, ownerId: string, keys: () => Pick<OysterKeyStore, "verify" | "touch">): OysterAuth;
package/dist/auth.js CHANGED
@@ -82,9 +82,33 @@ export function ownerKeyAuth(ownerKey, ownerId = "owner") {
82
82
  },
83
83
  };
84
84
  }
85
+ /** How stale a key's last-used time may be: calls inside this window do not re-stamp it. */
86
+ export const lastUsedGranularityMs = 5 * 60 * 1000;
85
87
  /** The owner key, or a named key admitted as its canonical Team-key actor. */
86
88
  export function ownerOrKeyAuth(ownerKey, ownerId, keys) {
87
89
  const owner = ownerKeyAuth(ownerKey, ownerId);
90
+ // When this isolate last tried to stamp each key. A key's "Last used" is
91
+ // accurate to `lastUsedGranularityMs`, so a burst of calls costs one write.
92
+ const lastStamp = new Map();
93
+ const stampLastUsed = async (keyId) => {
94
+ const now = Date.now();
95
+ const last = lastStamp.get(keyId);
96
+ if (last !== undefined && now - last < lastUsedGranularityMs)
97
+ return;
98
+ lastStamp.set(keyId, now);
99
+ // The call is already admitted: a failed stamp is reported, never fatal.
100
+ try {
101
+ const touched = await keys().touch(keyId);
102
+ if (touched.kind !== "ok")
103
+ console.error("Oyster key last-used stamp refused", {
104
+ keyId,
105
+ code: touched.error.code,
106
+ });
107
+ }
108
+ catch (error) {
109
+ console.error("Oyster key last-used stamp failed", keyId, error);
110
+ }
111
+ };
88
112
  return {
89
113
  resolve: (actor) => owner.resolve(actor),
90
114
  async authenticate(request) {
@@ -98,14 +122,17 @@ export function ownerOrKeyAuth(ownerKey, ownerId, keys) {
98
122
  // A revoked or expired key, or one belonging to a different owner (a
99
123
  // presented secret can never prove that on its own), authenticates as
100
124
  // no one; the owner-key result above still stands.
101
- return verified.kind === "ok" && verified.value.owner === ownerId
102
- ? {
103
- kind: "admitted",
104
- principal: {
105
- actor: { kind: "team-key", keyId: verified.value.keyId },
106
- },
107
- }
108
- : result;
125
+ if (verified.kind !== "ok" || verified.value.owner !== ownerId)
126
+ return result;
127
+ // The one place a named key is admitted for every door (Git, MCP, HTTP):
128
+ // stamp its Ear Tag last-used time here, so no caller can miss it.
129
+ await stampLastUsed(verified.value.keyId);
130
+ return {
131
+ kind: "admitted",
132
+ principal: {
133
+ actor: { kind: "team-key", keyId: verified.value.keyId },
134
+ },
135
+ };
109
136
  },
110
137
  login: (request) => owner.login?.(request) ??
111
138
  Promise.resolve(new Response("Sign-in is not available", { status: 404 })),
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Whether this Linux session is known to have no Secret Service: no session
3
+ * bus, or a bus that neither runs nor can activate `org.freedesktop.secrets`.
4
+ * The keyring binding reports an absent and a broken service alike as
5
+ * GenericFailure, so ask the bus for its typed name lists instead of reading
6
+ * error text. A present but locked or failing service is not absent; its
7
+ * errors stay fatal so private custody never silently downgrades to a file.
8
+ */
9
+ export declare function secretServiceAbsent(): Promise<boolean>;
@@ -0,0 +1,77 @@
1
+ import { once } from "node:events";
2
+ import { access } from "node:fs/promises";
3
+ import { join } from "node:path";
4
+ import process from "node:process";
5
+ import { Message, sessionBus } from "@jellybrick/dbus-next";
6
+ import * as z from "zod";
7
+ const secretServiceName = "org.freedesktop.secrets";
8
+ const missingBus = z.object({ code: z.enum(["ENOENT", "ECONNREFUSED"]) });
9
+ /** No address, X11 display or XDG bus socket: no session bus can be reached. */
10
+ async function noSessionBusAddress() {
11
+ if (process.env.DBUS_SESSION_BUS_ADDRESS || process.env.DISPLAY)
12
+ return false;
13
+ const runtime = process.env.XDG_RUNTIME_DIR;
14
+ if (!runtime)
15
+ return true;
16
+ try {
17
+ await access(join(runtime, "bus"));
18
+ return false;
19
+ }
20
+ catch (cause) {
21
+ if (missingBus.safeParse(cause).success)
22
+ return true;
23
+ throw cause;
24
+ }
25
+ }
26
+ /**
27
+ * Whether this Linux session is known to have no Secret Service: no session
28
+ * bus, or a bus that neither runs nor can activate `org.freedesktop.secrets`.
29
+ * The keyring binding reports an absent and a broken service alike as
30
+ * GenericFailure, so ask the bus for its typed name lists instead of reading
31
+ * error text. A present but locked or failing service is not absent; its
32
+ * errors stay fatal so private custody never silently downgrades to a file.
33
+ */
34
+ export async function secretServiceAbsent() {
35
+ if (await noSessionBusAddress())
36
+ return true;
37
+ let bus;
38
+ try {
39
+ bus = sessionBus();
40
+ const connected = bus;
41
+ const names = async (member) => {
42
+ const reply = await Promise.race([
43
+ connected.call(new Message({
44
+ destination: "org.freedesktop.DBus",
45
+ path: "/org/freedesktop/DBus",
46
+ interface: "org.freedesktop.DBus",
47
+ member,
48
+ })),
49
+ once(connected, "error", { signal: AbortSignal.timeout(3_000) }),
50
+ ]);
51
+ if (Array.isArray(reply)) {
52
+ const error = reply[0];
53
+ if (error instanceof Error)
54
+ throw error;
55
+ throw new Error("Cannot connect to the Secret Service session bus");
56
+ }
57
+ if (reply === null)
58
+ throw new Error("Cannot inspect the Secret Service session bus");
59
+ return z.array(z.string()).parse(reply.body[0]);
60
+ };
61
+ const [active, activatable] = await Promise.all([
62
+ names("ListNames"),
63
+ names("ListActivatableNames"),
64
+ ]);
65
+ return (!active.includes(secretServiceName) &&
66
+ !activatable.includes(secretServiceName));
67
+ }
68
+ catch (cause) {
69
+ // A stale address or socket path refuses the connection: no bus is running.
70
+ if (missingBus.safeParse(cause).success)
71
+ return true;
72
+ throw cause;
73
+ }
74
+ finally {
75
+ bus?.disconnect();
76
+ }
77
+ }
@@ -13,6 +13,7 @@
13
13
  // and --verbose streams them instead. Piped output or CI gets plain lines.
14
14
  import { spawn } from "node:child_process";
15
15
  import { startTrialComputer } from "./trial-computer.js";
16
+ import { secretServiceAbsent } from "./secret-service.js";
16
17
  import { createTrialOwner, prepareTrialPrivateState } from "./try-custody.js";
17
18
  import { randomBytes } from "node:crypto";
18
19
  import { encode as encodeBase64Url } from "effect/encoding/Base64Url";
@@ -22,7 +23,7 @@ import { runGit } from "../build/local-build.js";
22
23
  import { CleanupError, stopProcessGroup, awaitCleanup, } from "../build/process-group.js";
23
24
  import { InstallationObservationError } from "../installation-client.js";
24
25
  import { createWriteStream } from "node:fs";
25
- import { access, chmod, mkdir, mkdtemp, rename, readdir, rm, readFile, realpath, stat, writeFile, } from "node:fs/promises";
26
+ import { chmod, mkdir, mkdtemp, rename, readdir, rm, readFile, realpath, stat, writeFile, } from "node:fs/promises";
26
27
  import { createServer } from "node:net";
27
28
  import { createCredentialSealer, } from "@fungi.computer/veil/credential-store";
28
29
  import { basename, dirname, delimiter, join, resolve } from "node:path";
@@ -92,12 +93,15 @@ async function timedTask(ui, label, work) {
92
93
  throw cause;
93
94
  }
94
95
  }
95
- /** A failure that knows the exact next step; the command shows both. */
96
+ /**
97
+ * A failure that knows the exact next step; the command shows both, and the
98
+ * underlying reason when one caused it.
99
+ */
96
100
  class TryError extends Error {
97
101
  title;
98
102
  next;
99
- constructor(title, next) {
100
- super(`${title} ${next}`);
103
+ constructor(title, next, options) {
104
+ super(`${title} ${next}`, options);
101
105
  this.name = "TryError";
102
106
  this.title = title;
103
107
  this.next = next;
@@ -129,6 +133,16 @@ function innermostError(cause) {
129
133
  }
130
134
  return current;
131
135
  }
136
+ /**
137
+ * The innermost cause's message. A JSON syntax error quotes its input, which
138
+ * can be a saved keyring, so it is named instead of shown.
139
+ */
140
+ function failureReason(cause) {
141
+ const innermost = innermostError(cause);
142
+ return innermost instanceof SyntaxError
143
+ ? "a saved file is not valid JSON"
144
+ : innermost.message;
145
+ }
132
146
  const networkErrorCodes = new Set([
133
147
  "ENOTFOUND",
134
148
  "EAI_AGAIN",
@@ -143,7 +157,9 @@ function isNetworkFailure(error) {
143
157
  /** Show a failed `oyster try` as an error with its next step. */
144
158
  export function reportTryFailure(cause, ui) {
145
159
  if (cause instanceof TryError)
146
- ui.problem(cause.title, cause.next);
160
+ ui.problem(cause.cause === undefined
161
+ ? cause.title
162
+ : `${cause.title} Reason: ${failureReason(cause.cause)}`, cause.next);
147
163
  else
148
164
  ui.problem(cause instanceof Error ? cause.message : String(cause), `Run \`${command} --help\` for the options, or add --verbose to see the full output.`);
149
165
  }
@@ -419,26 +435,12 @@ const trialKeyringSchema = z.strictObject({
419
435
  keys: z.record(z.string(), z.string()),
420
436
  });
421
437
  const warnedCredentialFiles = new Set();
422
- /** A known-absent session bus permits a file; a locked/broken keychain does not. */
423
- async function headlessKeychain() {
424
- if (process.platform !== "linux" ||
425
- process.env.DBUS_SESSION_BUS_ADDRESS ||
426
- process.env.DISPLAY)
427
- return false;
428
- if (process.env.XDG_RUNTIME_DIR === undefined)
429
- return true;
430
- try {
431
- await access(join(process.env.XDG_RUNTIME_DIR, "bus"));
432
- return false;
433
- }
434
- catch (cause) {
435
- if (z.object({ code: z.literal("ENOENT") }).safeParse(cause).success)
436
- return true;
437
- throw cause;
438
- }
439
- }
440
- /** The host's keychain, never the library's nonpersistent keyutils fallback. */
441
- const osKeychain = async (account) => (await headlessKeychain())
438
+ /**
439
+ * The host's keychain, never the library's nonpersistent keyutils fallback.
440
+ * A Linux session known to have no Secret Service permits a file; a locked or
441
+ * broken keychain does not.
442
+ */
443
+ const osKeychain = async (account) => process.platform === "linux" && (await secretServiceAbsent())
442
444
  ? undefined
443
445
  : new (await import("@napi-rs/keyring")).AsyncEntry("fungi-oyster-credentials", account, { linux: { store: "secret-service" } });
444
446
  /** Convert native dotenv input once, after private custody has retained the key. */
@@ -561,7 +563,14 @@ export async function prepareTryModelKeyCustody(directory, keychain = osKeychain
561
563
  await chmod(path, 0o600);
562
564
  if (!warnedCredentialFiles.has(path)) {
563
565
  warnedCredentialFiles.add(path);
564
- process.stderr.write(`oyster: OS keychain unavailable (Linux Secret Service); wrapping keys stored/read in 0600 file ${JSON.stringify(path)}.\n`);
566
+ process.stderr.write([
567
+ "",
568
+ "oyster: WARNING: Linux Secret Service is not available on this machine.",
569
+ `oyster: This Oyster's model-key wrapping key is stored UNENCRYPTED in the 0600 file ${JSON.stringify(path)}.`,
570
+ "oyster: Anyone who can read that file as you can decrypt the model keys this Oyster saves.",
571
+ "oyster: To keep it in the OS keychain instead, install and start a Secret Service provider (for example gnome-keyring, or KeePassXC with Secret Service integration enabled) in your login session, then restart the Oyster.",
572
+ "",
573
+ ].join("\n"));
565
574
  }
566
575
  }
567
576
  else {
@@ -582,8 +591,8 @@ export async function prepareTryModelKeyCustody(directory, keychain = osKeychain
582
591
  await removeTrialCredentialBindings(directory);
583
592
  return keyring;
584
593
  }
585
- catch {
586
- throw new TryError("This Oyster could not prepare private model-key storage.", "Check the OS keychain and private credential-keyring.json, then restart the Oyster. Existing keys were not replaced.");
594
+ catch (cause) {
595
+ throw new TryError("This Oyster could not prepare private model-key storage.", "Check the OS keychain and private credential-keyring.json, then restart the Oyster. Existing keys were not replaced.", { cause });
587
596
  }
588
597
  }
589
598
  function startWrangler(input, keychain) {
@@ -63,6 +63,8 @@ export declare class OysterKeys extends DurableObject<OysterKeysEnv> {
63
63
  list(owner: string): ReturnType<KeyStore<OysterKeyCapability>["list"]>;
64
64
  /** Verify a bearer secret and return its current principal. */
65
65
  verify(secret: string): ReturnType<KeyStore<OysterKeyCapability>["verify"]>;
66
+ /** Stamp a key's last-used time; refuses `denied` for an unknown key. */
67
+ touch(keyId: string): ReturnType<KeyStore<OysterKeyCapability>["touch"]>;
66
68
  /** The live facts behind one key id, for the host's `keys.live` port; `null` for an unknown, revoked, expired or suspended key. */
67
69
  live(keyId: string): Promise<LiveOysterKey | null>;
68
70
  }
@@ -476,6 +476,10 @@ export class OysterKeys extends DurableObject {
476
476
  verify(secret) {
477
477
  return this.#store.verify(secret);
478
478
  }
479
+ /** Stamp a key's last-used time; refuses `denied` for an unknown key. */
480
+ touch(keyId) {
481
+ return this.#store.touch(keyId);
482
+ }
479
483
  /** The live facts behind one key id, for the host's `keys.live` port; `null` for an unknown, revoked, expired or suspended key. */
480
484
  async live(keyId) {
481
485
  const result = await this.#store.live({ keyId });
package/docs/api/auth.md CHANGED
@@ -28,6 +28,17 @@ const returningCookieName: "oyster_returning" = "oyster_returning";
28
28
 
29
29
  Marks a browser that has signed in here before; it carries no authority.
30
30
 
31
+ ---
32
+
33
+ ### lastUsedGranularityMs
34
+
35
+ ```ts
36
+ const lastUsedGranularityMs: number;
37
+ ```
38
+
39
+ How stale a key's last-used time may be: calls inside this window do not
40
+ re-stamp it.
41
+
31
42
  ## Functions
32
43
 
33
44
  ### ownerKeyAuth()
@@ -62,11 +73,11 @@ The owner key, or a named key admitted as its canonical Team-key actor.
62
73
 
63
74
  #### Parameters
64
75
 
65
- | Parameter | Type |
66
- | ---------- | ---------------------------------------------------------------------- |
67
- | `ownerKey` | `string` |
68
- | `ownerId` | `string` |
69
- | `keys` | () => `Pick`\<[`OysterKeyStore`](keys.md#oysterkeystore), `"verify"`\> |
76
+ | Parameter | Type |
77
+ | ---------- | ----------------------------------------------------------------------------------- |
78
+ | `ownerKey` | `string` |
79
+ | `ownerId` | `string` |
80
+ | `keys` | () => `Pick`\<[`OysterKeyStore`](keys.md#oysterkeystore), `"verify"` \| `"touch"`\> |
70
81
 
71
82
  #### Returns
72
83
 
@@ -198,6 +198,24 @@ Verify a bearer secret and return its current principal.
198
198
  `name`: `string`; `scope`: `Scope`\<`Capability`\>; `grantVersion`: `number`;
199
199
  `expiresAt`: `number` \| `null`; \}\>\>\>
200
200
 
201
+ ##### touch()
202
+
203
+ ```ts
204
+ touch(keyId): Promise<KeyOutcome<void>>;
205
+ ```
206
+
207
+ Stamp a key's last-used time; refuses `denied` for an unknown key.
208
+
209
+ ###### Parameters
210
+
211
+ | Parameter | Type |
212
+ | --------- | -------- |
213
+ | `keyId` | `string` |
214
+
215
+ ###### Returns
216
+
217
+ `Promise`\<`KeyOutcome`\<`void`\>\>
218
+
201
219
  ##### live()
202
220
 
203
221
  ```ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fungi.computer/oyster",
3
- "version": "0.39.0",
3
+ "version": "0.40.0",
4
4
  "author": "Levi <levi@technomancy.dev>",
5
5
  "description": "Oyster by Fungi: open-source Apps for people and AI agents. Try with one command or run on your own Cloudflare account.",
6
6
  "homepage": "https://docs.fungi.computer/oyster",
@@ -366,7 +366,7 @@
366
366
  "@fungi.computer/capnweb": "0.12.0-fungi.0",
367
367
  "@fungi.computer/caps": "0.12.1",
368
368
  "@fungi.computer/carrier": "0.2.5",
369
- "@fungi.computer/computer": "0.14.7",
369
+ "@fungi.computer/computer": "0.14.8",
370
370
  "@fungi.computer/computer-contract": "0.5.7",
371
371
  "@fungi.computer/darkroom": "0.11.7",
372
372
  "@fungi.computer/ear-tag": "0.1.0",
@@ -376,19 +376,20 @@
376
376
  "@fungi.computer/lantern": "0.4.2",
377
377
  "@fungi.computer/mycelium": "0.4.7",
378
378
  "@fungi.computer/nacre": "0.8.2",
379
- "@fungi.computer/parakeet": "0.14.0",
379
+ "@fungi.computer/parakeet": "0.14.1",
380
380
  "@fungi.computer/puffball": "0.12.0",
381
381
  "@fungi.computer/seam": "0.2.6",
382
- "@fungi.computer/shiitake": "0.21.0",
383
- "@fungi.computer/shiitake-extensions": "0.11.10",
382
+ "@fungi.computer/shiitake": "0.21.1",
383
+ "@fungi.computer/shiitake-extensions": "0.11.11",
384
384
  "@fungi.computer/sigils": "0.3.2",
385
385
  "@fungi.computer/sprite": "0.2.2",
386
386
  "@fungi.computer/sprite-zdog": "0.3.2",
387
- "@fungi.computer/veil": "0.8.1",
387
+ "@fungi.computer/veil": "0.8.2",
388
388
  "@fungi.computer/watchdog": "0.1.4",
389
389
  "@fungi.computer/whistle": "0.3.0",
390
390
  "@fungi.computer/workflows-wire": "0.5.4",
391
- "@fungi.computer/zookeeper": "0.0.42",
391
+ "@fungi.computer/zookeeper": "0.0.43",
392
+ "@jellybrick/dbus-next": "0.11.4",
392
393
  "@modelcontextprotocol/server": "2.0.0",
393
394
  "@msgpack/msgpack": "3.1.3",
394
395
  "@napi-rs/keyring": "2.1.2",