@fungi.computer/oyster 0.43.0 → 0.45.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.
@@ -0,0 +1,84 @@
1
+ import type { ConnectionSubject, ConnectionUsage, ConnectionView, HttpDestinations, Placement } from "@fungi.computer/veil/connections";
2
+ import type { CredentialRefusal, createAgentMcpConnections } from "./agent-connections.js";
3
+ import type { ModelKeyRecord } from "./model-key-vault.js";
4
+ import type { ModelKeyUsage } from "./model-key-usage.js";
5
+ /** One stored credential as the Vault page lists it. No value, ever. */
6
+ export type VaultCredential = Readonly<{
7
+ connectionId: string;
8
+ name: string;
9
+ label: string;
10
+ kind: "secret" | "mcp" | "openapi";
11
+ origin: string;
12
+ destinations: HttpDestinations | null;
13
+ credential: "value" | "sign-in" | "none";
14
+ placement: Placement | null;
15
+ state: Exclude<ConnectionView["state"], "revoked">;
16
+ version: number;
17
+ subjects: readonly ConnectionSubject[];
18
+ }>;
19
+ /** One owner request to the instance Vault; values travel in, never out. */
20
+ export type VaultCommand = Readonly<{
21
+ op: "read";
22
+ }> | Readonly<{
23
+ op: "addSecret";
24
+ name: string;
25
+ label?: string | undefined;
26
+ destinations: HttpDestinations;
27
+ placement: Placement;
28
+ secret: string;
29
+ }> | Readonly<{
30
+ op: "updateCredential";
31
+ connectionId: string;
32
+ expectedVersion: number;
33
+ label?: string | undefined;
34
+ destinations?: HttpDestinations | undefined;
35
+ secret?: string | undefined;
36
+ }> | Readonly<{
37
+ op: "revokeCredential";
38
+ connectionId: string;
39
+ expectedVersion: number;
40
+ }> | Readonly<{
41
+ op: "grantSecret" | "ungrantSecret";
42
+ connectionId: string;
43
+ subject: ConnectionSubject;
44
+ }> | Readonly<{
45
+ op: "usage";
46
+ connectionId: string;
47
+ }> | Readonly<{
48
+ op: "modelKeyUsage";
49
+ keyId: string;
50
+ }>;
51
+ /** Why the Vault refused a command; never a stored value. */
52
+ export type VaultRefusal = Readonly<{
53
+ error: CredentialRefusal["error"] | "duplicate_name" | "limit" | "invalid_endpoint" | "unsupported_subject";
54
+ }>;
55
+ /** The Vault page listing: every stored credential and model key, with no value. */
56
+ export type VaultView = Readonly<{
57
+ /** The owner is the only actor on an Oyster: everything is theirs to manage. */
58
+ role: Readonly<{
59
+ manageTeam: true;
60
+ managePersonal: true;
61
+ }>;
62
+ modelKeys: readonly ModelKeyRecord[];
63
+ credentials: readonly VaultCredential[];
64
+ /** Oyster derives fingerprints from every stored value: always complete. */
65
+ coverage: Readonly<{
66
+ state: "complete";
67
+ }>;
68
+ }>;
69
+ /** What one Vault command answers: a listing, an id, a version, usage or a refusal. */
70
+ export type VaultResult = VaultView | Readonly<{
71
+ connectionId: string;
72
+ }> | Readonly<{
73
+ version: number;
74
+ }> | Readonly<{
75
+ ok: true;
76
+ }> | Readonly<{
77
+ usage: readonly ConnectionUsage[] | readonly ModelKeyUsage[];
78
+ }> | VaultRefusal;
79
+ /** The instance's Vault: its connections' credentials and model keys, write-only. */
80
+ export declare function createInstanceVault(owners: {
81
+ connections: ReturnType<typeof createAgentMcpConnections>;
82
+ modelKeys: () => Promise<readonly ModelKeyRecord[]>;
83
+ modelKeyUsage: (keyId: string) => readonly ModelKeyUsage[];
84
+ }): (command: VaultCommand) => Promise<VaultResult>;
@@ -0,0 +1,64 @@
1
+ const credentialOf = (view) => view.state === "revoked"
2
+ ? []
3
+ : [
4
+ {
5
+ connectionId: view.connectionId,
6
+ name: view.name,
7
+ label: view.label,
8
+ kind: view.surface.kind === "http" ? "secret" : view.surface.kind,
9
+ origin: view.surface.origin,
10
+ destinations: view.surface.destinations ?? null,
11
+ credential: view.credential.kind === "static"
12
+ ? "value"
13
+ : view.credential.kind === "oauth"
14
+ ? "sign-in"
15
+ : "none",
16
+ placement: view.credential.kind === "static"
17
+ ? view.credential.placement
18
+ : null,
19
+ state: view.state,
20
+ version: view.version,
21
+ subjects: view.grants.map((grant) => grant.subject),
22
+ },
23
+ ];
24
+ /** The instance's Vault: its connections' credentials and model keys, write-only. */
25
+ export function createInstanceVault(owners) {
26
+ const { connections } = owners;
27
+ return async (command) => {
28
+ switch (command.op) {
29
+ case "read":
30
+ return {
31
+ role: { manageTeam: true, managePersonal: true },
32
+ modelKeys: await owners.modelKeys(),
33
+ credentials: (await connections.credentials()).flatMap(credentialOf),
34
+ coverage: { state: "complete" },
35
+ };
36
+ case "addSecret":
37
+ return connections.addSecret(command);
38
+ case "updateCredential":
39
+ return connections.updateCredential(command);
40
+ case "revokeCredential": {
41
+ const held = (await connections.credentials()).find((view) => view.connectionId === command.connectionId);
42
+ if (held === undefined)
43
+ return { error: "not_found" };
44
+ if (held.version !== command.expectedVersion)
45
+ return { error: "conflict" };
46
+ // An HTTP secret is revoked whole; a Connection only loses its value.
47
+ if (held.surface.kind !== "http")
48
+ return connections.clearCredential(command);
49
+ return (await connections.remove(command.connectionId))
50
+ ? { ok: true }
51
+ : { error: "not_found" };
52
+ }
53
+ case "grantSecret":
54
+ return connections.grantSecret(command.connectionId, command.subject);
55
+ case "ungrantSecret":
56
+ await connections.ungrantSecret(command.connectionId, command.subject);
57
+ return { ok: true };
58
+ case "usage":
59
+ return { usage: await connections.secretUsage(command.connectionId) };
60
+ case "modelKeyUsage":
61
+ return { usage: owners.modelKeyUsage(command.keyId) };
62
+ }
63
+ };
64
+ }
@@ -60,7 +60,8 @@ declare const OysterInstallationExecutor_base: new (ctx: ExecutionContext, env:
60
60
  /** Private loopback execution uses this root's ordinary host composition. */
61
61
  export declare class OysterInstallationExecutor extends OysterInstallationExecutor_base {
62
62
  }
63
- /** The Computer's egress gateway: its own HTTPS Git back into this Worker. */
63
+ /** The Computer's egress gateway: its own HTTPS Git back into this Worker,
64
+ * and the Vault lane through the Agent directory that owns each secret. */
64
65
  export declare class OysterComputerEgress extends WorkerEntrypoint<StandaloneEnv, OysterComputerEgressProps> {
65
66
  fetch(request: Request): Promise<Response>;
66
67
  }
@@ -155,16 +155,26 @@ const oyster = createOysterGitWorker(oysterRoot);
155
155
  /** Private loopback execution uses this root's ordinary host composition. */
156
156
  export class OysterInstallationExecutor extends installationWorkerEntrypoint((env, scope) => oysterRoot.hostFor(env, scope)) {
157
157
  }
158
- /** The Computer's egress gateway: its own HTTPS Git back into this Worker. */
158
+ /** The Computer's egress gateway: its own HTTPS Git back into this Worker,
159
+ * and the Vault lane through the Agent directory that owns each secret. */
159
160
  export class OysterComputerEgress extends WorkerEntrypoint {
160
161
  fetch(request) {
161
162
  const computerObjectId = this.ctx.props.computerObjectId;
162
163
  const registry = computerRegistry(this.env);
164
+ const computer = () => this.env.COMPUTER.get(this.env.COMPUTER.idFromString(computerObjectId));
165
+ // The Agent directory that owns each secret, not the Git owner's narrow view.
166
+ const directories = this.env.AGENT_DIRECTORY;
163
167
  return serveOysterComputerEgress(request, {
164
168
  origin: this.env.OYSTER_ORIGIN,
165
169
  computerId: computerObjectId,
166
170
  publicEgress: this.env.COMPUTER_PUBLIC_EGRESS,
167
- internetAccess: () => this.env.COMPUTER.get(this.env.COMPUTER.idFromString(computerObjectId)).internetAccess(),
171
+ internetAccess: () => computer().internetAccess(),
172
+ vault: {
173
+ admit: (reference) => computer().admitVaultReference(reference),
174
+ send: (admission, data) => directories
175
+ .getByName(admission.owner)
176
+ .sendComputerVault(admission, data),
177
+ },
168
178
  build: {
169
179
  gitPassFor: (target) => registry.buildGitPassFor(computerObjectId, target),
170
180
  exchangeTemplate: (repository, request) => registry.exchangeBuildTemplate(computerObjectId, repository, request),
@@ -368,6 +368,7 @@ type OysterAgents = Readonly<{
368
368
  error: ModelKeyRefusal;
369
369
  }>>;
370
370
  removeModelKey: Promise<"deleted" | "absent">;
371
+ vault: Promise<VaultResult>;
371
372
  connections: Promise<readonly Readonly<{
372
373
  connectionId: string;
373
374
  name: string;
@@ -383,11 +384,11 @@ type OysterAgents = Readonly<{
383
384
  }>[]>;
384
385
  addConnection: Promise<
385
386
  | Readonly<{
386
- connectionId: string;
387
- authorizeUrl: string | null;
387
+ error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
388
388
  }>
389
389
  | Readonly<{
390
- error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
390
+ connectionId: string;
391
+ authorizeUrl: string | null;
391
392
  }>>;
392
393
  grantConnection: Promise<
393
394
  | Readonly<{
@@ -430,6 +431,18 @@ restores only archive-paused schedules on unarchive.
430
431
 
431
432
  ---
432
433
 
434
+ ### CredentialRefusal
435
+
436
+ ```ts
437
+ type CredentialRefusal = Readonly<{
438
+ error: "not_found" | "conflict" | "denied" | "invalid_input";
439
+ }>;
440
+ ```
441
+
442
+ Why the Vault could not change a stored credential; never its value.
443
+
444
+ ---
445
+
433
446
  ### AgentModelChoice
434
447
 
435
448
  ```ts
@@ -468,6 +481,27 @@ Cloudflare account and token.
468
481
 
469
482
  ---
470
483
 
484
+ ### ModelKeyUsage
485
+
486
+ ```ts
487
+ type ModelKeyUsage = Readonly<{
488
+ keyId: string;
489
+ subject: Readonly<{
490
+ kind: "agent";
491
+ id: string;
492
+ }> | null;
493
+ outcome: "upstream_status" | "failed";
494
+ status: number | null;
495
+ firstAt: number;
496
+ lastAt: number;
497
+ count: number;
498
+ }>;
499
+ ```
500
+
501
+ One recorded use, as the Vault lists it.
502
+
503
+ ---
504
+
471
505
  ### ModelKeyRefusal
472
506
 
473
507
  ```ts
@@ -516,6 +550,136 @@ What the owner submits to seal one provider key.
516
550
 
517
551
  ---
518
552
 
553
+ ### VaultCredential
554
+
555
+ ```ts
556
+ type VaultCredential = Readonly<{
557
+ connectionId: string;
558
+ name: string;
559
+ label: string;
560
+ kind: "secret" | "mcp" | "openapi";
561
+ origin: string;
562
+ destinations: HttpDestinations | null;
563
+ credential: "value" | "sign-in" | "none";
564
+ placement: Placement | null;
565
+ state: Exclude<ConnectionView["state"], "revoked">;
566
+ version: number;
567
+ subjects: readonly ConnectionSubject[];
568
+ }>;
569
+ ```
570
+
571
+ One stored credential as the Vault page lists it. No value, ever.
572
+
573
+ ---
574
+
575
+ ### VaultCommand
576
+
577
+ ```ts
578
+ type VaultCommand =
579
+ | Readonly<{
580
+ op: "read";
581
+ }>
582
+ | Readonly<{
583
+ op: "addSecret";
584
+ name: string;
585
+ label?: string;
586
+ destinations: HttpDestinations;
587
+ placement: Placement;
588
+ secret: string;
589
+ }>
590
+ | Readonly<{
591
+ op: "updateCredential";
592
+ connectionId: string;
593
+ expectedVersion: number;
594
+ label?: string;
595
+ destinations?: HttpDestinations;
596
+ secret?: string;
597
+ }>
598
+ | Readonly<{
599
+ op: "revokeCredential";
600
+ connectionId: string;
601
+ expectedVersion: number;
602
+ }>
603
+ | Readonly<{
604
+ op: "grantSecret" | "ungrantSecret";
605
+ connectionId: string;
606
+ subject: ConnectionSubject;
607
+ }>
608
+ | Readonly<{
609
+ op: "usage";
610
+ connectionId: string;
611
+ }>
612
+ | Readonly<{
613
+ op: "modelKeyUsage";
614
+ keyId: string;
615
+ }>;
616
+ ```
617
+
618
+ One owner request to the instance Vault; values travel in, never out.
619
+
620
+ ---
621
+
622
+ ### VaultRefusal
623
+
624
+ ```ts
625
+ type VaultRefusal = Readonly<{
626
+ error:
627
+ | CredentialRefusal["error"]
628
+ | "duplicate_name"
629
+ | "limit"
630
+ | "invalid_endpoint"
631
+ | "unsupported_subject";
632
+ }>;
633
+ ```
634
+
635
+ Why the Vault refused a command; never a stored value.
636
+
637
+ ---
638
+
639
+ ### VaultView
640
+
641
+ ```ts
642
+ type VaultView = Readonly<{
643
+ role: Readonly<{
644
+ manageTeam: true;
645
+ managePersonal: true;
646
+ }>;
647
+ modelKeys: readonly ModelKeyRecord[];
648
+ credentials: readonly VaultCredential[];
649
+ coverage: Readonly<{
650
+ state: "complete";
651
+ }>;
652
+ }>;
653
+ ```
654
+
655
+ The Vault page listing: every stored credential and model key, with no value.
656
+
657
+ ---
658
+
659
+ ### VaultResult
660
+
661
+ ```ts
662
+ type VaultResult =
663
+ | VaultView
664
+ | Readonly<{
665
+ connectionId: string;
666
+ }>
667
+ | Readonly<{
668
+ version: number;
669
+ }>
670
+ | Readonly<{
671
+ ok: true;
672
+ }>
673
+ | Readonly<{
674
+ usage: readonly ConnectionUsage[] | readonly ModelKeyUsage[];
675
+ }>
676
+ | VaultRefusal;
677
+ ```
678
+
679
+ What one Vault command answers: a listing, an id, a version, usage or a refusal.
680
+
681
+ ---
682
+
519
683
  ### StarterOutcome
520
684
 
521
685
  ```ts