@fungi.computer/oyster 0.37.2 → 0.38.1

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 (88) hide show
  1. package/README.md +5 -4
  2. package/dist/agents.js +9 -2
  3. package/dist/app-builds.d.ts +1 -1
  4. package/dist/app-region.d.ts +94 -0
  5. package/dist/app-region.js +316 -0
  6. package/dist/authorization.d.ts +58 -9
  7. package/dist/authorization.js +56 -11
  8. package/dist/backend-request.d.ts +4 -0
  9. package/dist/backend-request.js +3 -10
  10. package/dist/boot-host-script.js +1 -1
  11. package/dist/build/candidate-builder.d.ts +1 -1
  12. package/dist/build/candidate-cli.mjs +284 -17
  13. package/dist/build/effect.d.ts +3 -3
  14. package/dist/build/submission-contract.d.ts +1 -1
  15. package/dist/build/workspace-build.d.ts +2 -2
  16. package/dist/channels/discord-replies.d.ts +8 -1
  17. package/dist/channels/discord-replies.js +80 -29
  18. package/dist/cloudflare.d.ts +1 -0
  19. package/dist/cloudflare.js +12 -2
  20. package/dist/credential-migration-001.d.ts +14 -0
  21. package/dist/credential-migration-001.js +13 -0
  22. package/dist/credential-migration-002.d.ts +38 -0
  23. package/dist/credential-migration-002.js +74 -0
  24. package/dist/embed-metafiles.js +2 -2
  25. package/dist/embed-scripts.js +1 -1
  26. package/dist/host.d.ts +2 -0
  27. package/dist/host.js +23 -13
  28. package/dist/index.d.ts +15 -1
  29. package/dist/index.js +19 -0
  30. package/dist/invocation.d.ts +165 -0
  31. package/dist/invocation.js +67 -0
  32. package/dist/keys.d.ts +4 -3
  33. package/dist/keys.js +5 -4
  34. package/dist/mcp-owner.d.ts +4 -3
  35. package/dist/mcp-owner.js +3 -2
  36. package/dist/page/mount.js +5 -1
  37. package/dist/page/region.d.ts +6 -0
  38. package/dist/page/region.js +12 -0
  39. package/dist/page-config.d.ts +2 -0
  40. package/dist/page-config.js +2 -0
  41. package/dist/page-script.js +2 -2
  42. package/dist/source/seed-receipt.d.ts +1 -1
  43. package/dist/source/template-seed.d.ts +1 -1
  44. package/dist/standalone/agent-connections.d.ts +49 -1
  45. package/dist/standalone/agent-connections.js +101 -12
  46. package/dist/standalone/agent-self.js +2 -1
  47. package/dist/standalone/agents.d.ts +7 -3
  48. package/dist/standalone/agents.js +42 -19
  49. package/dist/standalone/computer-fleet.d.ts +12 -6
  50. package/dist/standalone/computer-fleet.js +70 -29
  51. package/dist/standalone/computer.js +39 -14
  52. package/dist/standalone/instance.d.ts +3 -1
  53. package/dist/standalone/instance.js +8 -0
  54. package/dist/standalone/model-key-vault.d.ts +33 -4
  55. package/dist/standalone/model-key-vault.js +74 -17
  56. package/dist/standalone/preview.js +11 -10
  57. package/dist/standalone/try-cli.d.ts +12 -2
  58. package/dist/standalone/try-cli.js +170 -32
  59. package/dist/standalone/try-worker.d.ts +2 -0
  60. package/dist/standalone/try-worker.js +15 -0
  61. package/dist/standalone/worker.js +3 -3
  62. package/dist/standalone/workflow-host.d.ts +1 -1
  63. package/dist/standalone/workflows.d.ts +3 -3
  64. package/dist/standalone/workflows.js +7 -0
  65. package/dist/testing/capabilities.d.ts +2 -0
  66. package/dist/testing/capabilities.js +2 -0
  67. package/dist/webhook-custody.d.ts +14 -3
  68. package/dist/webhook-custody.js +165 -43
  69. package/dist/webhooks.d.ts +1 -1
  70. package/dist/webhooks.js +15 -3
  71. package/dist/workers-git.d.ts +24 -8
  72. package/dist/workers-git.js +105 -15
  73. package/dist/workers.d.ts +16 -0
  74. package/dist/workers.js +95 -5
  75. package/docs/api/apps.md +31 -31
  76. package/docs/api/authorization.md +119 -17
  77. package/docs/api/build-contract.md +8 -8
  78. package/docs/api/build.md +163 -174
  79. package/docs/api/cloudflare.md +171 -0
  80. package/docs/api/host.md +1 -0
  81. package/docs/api/index.md +23 -0
  82. package/docs/api/invocation.md +623 -23
  83. package/docs/api/keys.md +6 -6
  84. package/docs/api/pack.md +3 -3
  85. package/docs/api/page/mount.md +22 -20
  86. package/docs/api/workers-git.md +273 -157
  87. package/docs/api/workers.md +257 -175
  88. package/package.json +19 -18
@@ -1,6 +1,7 @@
1
1
  import { createHash, randomBytes } from "node:crypto";
2
2
  import { Base64Url } from "effect/encoding";
3
3
  import { z } from "zod";
4
+ import { CredentialError } from "@fungi.computer/veil/credential-store";
4
5
  import { armedWorkflowTriggerSchema, } from "@fungi.computer/braid/runtime";
5
6
  import { verifyFungiV1, verifyGithub, verifyStandardWebhooks, standardWebhookSecret, } from "@fungi.computer/veil/event-verifiers";
6
7
  export const workflowWebhookVerifierSchema = z.enum([
@@ -9,10 +10,13 @@ export const workflowWebhookVerifierSchema = z.enum([
9
10
  "standard-webhooks",
10
11
  ]);
11
12
  const idSchema = z.string().min(1).max(256);
13
+ const secretSchema = z.string().regex(/^[A-Za-z0-9_-]{43}$/u);
14
+ const generationSchema = z.number().int().positive();
12
15
  const keySchema = z.strictObject({
13
- secret: z.string().regex(/^[A-Za-z0-9_-]{43}$/u),
14
- generation: z.number().int().positive(),
16
+ secret: secretSchema,
17
+ generation: generationSchema,
15
18
  });
19
+ /** The open row a verification holds in memory; never stored like this. */
16
20
  const rowSchema = z.strictObject({
17
21
  id: idSchema,
18
22
  creator: idSchema,
@@ -23,6 +27,21 @@ const rowSchema = z.strictObject({
23
27
  .extend({ expiresAt: z.number().int().nonnegative() })
24
28
  .nullable(),
25
29
  });
30
+ /** The stored record: everything but the key bytes, which are sealed. */
31
+ const recordSchema = rowSchema.extend({
32
+ current: z.strictObject({ generation: generationSchema }),
33
+ previous: z
34
+ .strictObject({
35
+ generation: generationSchema,
36
+ expiresAt: z.number().int().nonnegative(),
37
+ })
38
+ .nullable(),
39
+ });
40
+ const secretsSchema = z.strictObject({
41
+ current: secretSchema,
42
+ previous: secretSchema.nullable(),
43
+ });
44
+ const storedSchema = z.strictObject({ record: z.string(), sealed: z.string() });
26
45
  const refused = { kind: "refused" };
27
46
  const DAY = 24 * 60 * 60 * 1000;
28
47
  const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
@@ -31,6 +50,58 @@ const verifiers = {
31
50
  github: verifyGithub,
32
51
  "standard-webhooks": verifyStandardWebhooks,
33
52
  };
53
+ const context = (id) => ["workflow-webhook", id];
54
+ function ensureKeys(sql) {
55
+ sql.exec(`CREATE TABLE IF NOT EXISTS oyster_workflow_webhook_keys (
56
+ id TEXT PRIMARY KEY, record TEXT NOT NULL, sealed TEXT NOT NULL
57
+ ) STRICT`);
58
+ }
59
+ async function sealRow(sealer, row) {
60
+ const record = recordSchema.parse({
61
+ ...row,
62
+ current: { generation: row.current.generation },
63
+ previous: row.previous === null
64
+ ? null
65
+ : {
66
+ generation: row.previous.generation,
67
+ expiresAt: row.previous.expiresAt,
68
+ },
69
+ });
70
+ const secrets = secretsSchema.parse({
71
+ current: row.current.secret,
72
+ previous: row.previous?.secret ?? null,
73
+ });
74
+ return {
75
+ id: row.id,
76
+ record: JSON.stringify(record),
77
+ sealed: await sealer.seal(context(row.id), JSON.stringify(secrets)),
78
+ };
79
+ }
80
+ /** A stored record that still names a key, or a key that no longer opens, refuses. */
81
+ async function openRow(sealer, stored) {
82
+ const record = recordSchema.parse(JSON.parse(stored.record));
83
+ const secrets = secretsSchema.parse(JSON.parse(await sealer.open(context(record.id), stored.sealed)));
84
+ if ((record.previous === null) !== (secrets.previous === null))
85
+ throw new CredentialError("denied");
86
+ return rowSchema.parse({
87
+ ...record,
88
+ current: { ...record.current, secret: secrets.current },
89
+ previous: record.previous === null
90
+ ? null
91
+ : { ...record.previous, secret: secrets.previous },
92
+ });
93
+ }
94
+ /** Migration 002's step: the plaintext JSON record gains its sealed key bytes. */
95
+ export const workflowWebhookKeys002 = {
96
+ table: "oyster_workflow_webhook_keys",
97
+ plaintext: (columns) => columns.length > 0 && !columns.includes("sealed"),
98
+ secretColumns: ["record"],
99
+ ensure: ensureKeys,
100
+ async seal(sealer, raw) {
101
+ const legacy = z.object({ record: z.string() }).parse(raw);
102
+ return sealRow(sealer, rowSchema.parse(JSON.parse(legacy.record)));
103
+ },
104
+ };
34
105
  function matchingEvent(row, scheme, current, previous, now) {
35
106
  if (row?.verifier !== scheme)
36
107
  return null;
@@ -71,45 +142,64 @@ function deliveryIdentity(verifier, eventId, body) {
71
142
  * handed to ingress. No read-existing-secret method, master key or generation
72
143
  * derivation exists. Host authentication supplies the principal; owner() must
73
144
  * resolve CURRENT server-side ownership, not trust a caller-supplied role.
145
+ * Key bytes rest only in the owner's S1 envelope; `ready` is the host's
146
+ * migration 002, which runs before any row is read or written.
74
147
  */
75
148
  export function workflowWebhookCustody(options) {
76
149
  const { sql } = options;
77
- sql.exec(`CREATE TABLE IF NOT EXISTS oyster_workflow_webhook_keys (
78
- id TEXT PRIMARY KEY, record TEXT NOT NULL
79
- ) STRICT`);
150
+ // A store still in the plaintext shape keeps it until `ready` migrates it.
151
+ ensureKeys(sql);
80
152
  sql.exec(`CREATE TABLE IF NOT EXISTS oyster_workflow_webhook_revoked (
81
153
  id TEXT PRIMARY KEY
82
154
  ) STRICT`);
155
+ const ready = () => options.ready();
156
+ const sealer = () => {
157
+ if (options.sealer === undefined)
158
+ throw new CredentialError("unavailable");
159
+ return options.sealer;
160
+ };
83
161
  const read = (id) => {
84
162
  const raw = sql
85
- .exec("SELECT record FROM oyster_workflow_webhook_keys WHERE id=?", id)
163
+ .exec("SELECT record, sealed FROM oyster_workflow_webhook_keys WHERE id=?", id)
86
164
  .toArray()[0];
87
- if (raw === undefined)
88
- return null;
89
- const envelope = z.object({ record: z.string() }).parse(raw);
90
- return rowSchema.parse(JSON.parse(envelope.record));
91
- };
92
- const write = (row) => {
93
- sql.exec("INSERT INTO oyster_workflow_webhook_keys(id,record) VALUES(?,?) ON CONFLICT(id) DO UPDATE SET record=excluded.record", row.id, JSON.stringify(row));
165
+ return raw === undefined ? null : storedSchema.parse(raw);
94
166
  };
167
+ /** Compare-and-swap on the sealed bytes; every seal draws a fresh IV. */
168
+ const replace = (before, next) => sql
169
+ .exec("UPDATE oyster_workflow_webhook_keys SET record=?, sealed=? WHERE id=? AND sealed=? RETURNING id", next.record, next.sealed, next.id, before.sealed)
170
+ .toArray().length > 0;
95
171
  const newKey = (generation) => ({
96
172
  secret: Base64Url.encode(randomBytes(32)),
97
173
  generation,
98
174
  });
99
175
  const dummy = Base64Url.encode(randomBytes(32));
176
+ // Unknown IDs open a sealed decoy, so a known ID costs the same work.
177
+ let decoy;
178
+ const openDecoy = async (current) => {
179
+ // Kept only once sealed; a failed seal refuses this delivery and retries.
180
+ decoy ??= await current.seal(["workflow-webhook-decoy"], JSON.stringify({ current: dummy, previous: null }));
181
+ await current.open(["workflow-webhook-decoy"], decoy);
182
+ };
100
183
  const disclosure = (row, actor) => actor !== row.creator
101
184
  ? null
102
185
  : row.verifier === "standard-webhooks"
103
186
  ? standardWebhookSecret(row.current.secret)
104
187
  : row.current.secret;
188
+ /** Open, change and swap one owned row; a concurrent change refuses. */
105
189
  const withOwnedBinding = async (principal, bindingId, update) => {
106
190
  const actor = await options.owner(principal);
107
191
  if (actor === null)
108
192
  return refused;
109
- return options.transactionSync(() => {
110
- const row = read(idSchema.parse(bindingId));
111
- return row === null ? refused : update(row, actor);
112
- });
193
+ await ready();
194
+ const stored = read(idSchema.parse(bindingId));
195
+ if (stored === null)
196
+ return refused;
197
+ const current = sealer();
198
+ const change = update(await openRow(current, stored), actor);
199
+ if (!("next" in change))
200
+ return refused;
201
+ const next = await sealRow(current, change.next);
202
+ return options.transactionSync(() => replace(stored, next) ? change.result : refused);
113
203
  };
114
204
  return {
115
205
  async create(principal, bindingId, verifier, rawBinding) {
@@ -122,21 +212,23 @@ export function workflowWebhookCustody(options) {
122
212
  const binding = armedWorkflowTriggerSchema.parse(rawBinding);
123
213
  if (binding.armedBy !== creator || binding.armedVia !== null)
124
214
  return refused;
215
+ await ready();
216
+ const row = rowSchema.parse({
217
+ id,
218
+ creator,
219
+ binding,
220
+ verifier: scheme,
221
+ current: newKey(1),
222
+ previous: null,
223
+ });
224
+ const stored = await sealRow(sealer(), row);
125
225
  return options.transactionSync(() => {
126
226
  if (read(id) !== null ||
127
227
  sql
128
228
  .exec("SELECT id FROM oyster_workflow_webhook_revoked WHERE id=?", id)
129
229
  .toArray().length > 0)
130
230
  return refused;
131
- const row = rowSchema.parse({
132
- id,
133
- creator,
134
- binding,
135
- verifier: scheme,
136
- current: newKey(1),
137
- previous: null,
138
- });
139
- write(row);
231
+ sql.exec("INSERT INTO oyster_workflow_webhook_keys(id,record,sealed) VALUES(?,?,?)", stored.id, stored.record, stored.sealed);
140
232
  return {
141
233
  kind: "created",
142
234
  bindingId: row.id,
@@ -149,36 +241,48 @@ export function workflowWebhookCustody(options) {
149
241
  return withOwnedBinding(principal, bindingId, (row, actor) => {
150
242
  if (row.previous !== null && row.previous.expiresAt > options.now())
151
243
  return refused;
152
- row.previous = { ...row.current, expiresAt: options.now() + DAY };
153
- row.current = newKey(row.current.generation + 1);
154
- write(row);
155
- return { kind: "rotated", secret: disclosure(row, actor) };
244
+ const next = {
245
+ ...row,
246
+ previous: { ...row.current, expiresAt: options.now() + DAY },
247
+ current: newKey(row.current.generation + 1),
248
+ };
249
+ return {
250
+ next,
251
+ result: { kind: "rotated", secret: disclosure(next, actor) },
252
+ };
156
253
  });
157
254
  },
158
255
  async retirePrevious(principal, bindingId) {
159
- return withOwnedBinding(principal, bindingId, (row) => {
160
- row.previous = null;
161
- write(row);
162
- return { kind: "retired" };
163
- });
256
+ return withOwnedBinding(principal, bindingId, (row) => ({
257
+ next: { ...row, previous: null },
258
+ result: { kind: "retired" },
259
+ }));
164
260
  },
165
261
  async revoke(principal, bindingId) {
166
- return withOwnedBinding(principal, bindingId, (row) => {
262
+ const actor = await options.owner(principal);
263
+ if (actor === null)
264
+ return refused;
265
+ await ready();
266
+ const id = idSchema.parse(bindingId);
267
+ return options.transactionSync(() => {
268
+ if (read(id) === null)
269
+ return refused;
167
270
  // Delete ALL key bytes immediately; the tombstone prevents redisclosure.
168
- sql.exec("DELETE FROM oyster_workflow_webhook_keys WHERE id=?", row.id);
169
- sql.exec("INSERT INTO oyster_workflow_webhook_revoked(id) VALUES(?) ON CONFLICT DO NOTHING", row.id);
271
+ sql.exec("DELETE FROM oyster_workflow_webhook_keys WHERE id=?", id);
272
+ sql.exec("INSERT INTO oyster_workflow_webhook_revoked(id) VALUES(?) ON CONFLICT DO NOTHING", id);
170
273
  return { kind: "revoked" };
171
274
  });
172
275
  },
173
276
  async list(principal, after = null) {
174
277
  if ((await options.owner(principal)) === null)
175
278
  return { bindings: [], next: null };
279
+ await ready();
176
280
  const cursor = after === null ? "" : idSchema.parse(after);
177
281
  const rows = sql
178
282
  .exec("SELECT record FROM oyster_workflow_webhook_keys WHERE id>? ORDER BY id LIMIT 101", cursor)
179
283
  .toArray();
180
284
  const bindings = rows.slice(0, 100).map((raw) => {
181
- const row = rowSchema.parse(JSON.parse(z.object({ record: z.string() }).parse(raw).record));
285
+ const row = recordSchema.parse(JSON.parse(z.object({ record: z.string() }).parse(raw).record));
182
286
  return {
183
287
  bindingId: row.id,
184
288
  verifier: row.verifier,
@@ -195,13 +299,31 @@ export function workflowWebhookCustody(options) {
195
299
  verification: {
196
300
  /** Final owner-store check for an already verified durable reservation. */
197
301
  isActive(bindingId) {
198
- return read(idSchema.parse(bindingId)) !== null;
302
+ return (sql
303
+ .exec("SELECT id FROM oyster_workflow_webhook_keys WHERE id=?", idSchema.parse(bindingId))
304
+ .toArray().length > 0);
199
305
  },
200
- /** Always does six maintained verifier checks, including unknown IDs. */
201
- verify(delivery) {
202
- const row = idSchema.safeParse(delivery.bindingId).success
306
+ /**
307
+ * Always opens one envelope and does six maintained verifier checks,
308
+ * including unknown IDs. Without a keyring it refuses as unavailable.
309
+ */
310
+ async verify(delivery) {
311
+ await ready();
312
+ const current = sealer();
313
+ const stored = idSchema.safeParse(delivery.bindingId).success
203
314
  ? read(delivery.bindingId)
204
315
  : null;
316
+ if (stored === null)
317
+ await openDecoy(current);
318
+ // A row that does not open (old shape, tampered) refuses like an unknown one.
319
+ const row = stored === null
320
+ ? null
321
+ : await openRow(current, stored).catch((cause) => {
322
+ if (cause instanceof CredentialError &&
323
+ cause.code === "unavailable")
324
+ throw cause;
325
+ return null;
326
+ });
205
327
  const request = {
206
328
  headers: delivery.headers,
207
329
  body: delivery.body,
@@ -57,7 +57,7 @@ export declare function workflowWebhookControlResponse<Principal>(webhooks: Retu
57
57
  * host's ordinary idempotent launch ensures its recorded engine instance.
58
58
  * No separate intake state machine or run/settlement store exists here.
59
59
  */
60
- export declare function createWorkflowWebhooks<Principal>(options: Parameters<typeof workflowWebhookCustody<Principal>>[0] & {
60
+ export declare function createWorkflowWebhooks<Principal>(options: Omit<Parameters<typeof workflowWebhookCustody<Principal>>[0], "ready"> & {
61
61
  scope: Readonly<{
62
62
  host: string;
63
63
  tenant: string;
package/dist/webhooks.js CHANGED
@@ -3,9 +3,10 @@ import { z } from "zod";
3
3
  import * as Effect from "effect/Effect";
4
4
  import * as Result from "effect/Result";
5
5
  import { armedWorkflowTriggerSchema, workflowTriggerTargetSchema, } from "@fungi.computer/braid/runtime";
6
- import { workflowWebhookCustody, workflowWebhookVerifierSchema, } from "./webhook-custody.js";
6
+ import { workflowWebhookCustody, workflowWebhookKeys002, workflowWebhookVerifierSchema, } from "./webhook-custody.js";
7
7
  import { workflowWebhookIngress, } from "./webhook-ingress.js";
8
8
  import { workflowWebhookAbuse } from "./webhook-abuse.js";
9
+ import { credentialMigration002 } from "./credential-migration-002.js";
9
10
  const ids = defineIdFamily({
10
11
  family: "workflow-webhooks",
11
12
  version: 1,
@@ -51,7 +52,18 @@ export async function workflowWebhookControlResponse(webhooks, principal, comman
51
52
  * No separate intake state machine or run/settlement store exists here.
52
53
  */
53
54
  export function createWorkflowWebhooks(options) {
54
- const custody = workflowWebhookCustody(options);
55
+ // Migration 002 seals plaintext keys before any row is read or written.
56
+ const ready = credentialMigration002({
57
+ store: options,
58
+ sealer: options.sealer,
59
+ tables: [workflowWebhookKeys002],
60
+ });
61
+ const custody = workflowWebhookCustody({ ...options, ready });
62
+ // Seal at composition too, so an idle store does not keep plaintext keys.
63
+ void Effect.runPromise(Effect.result(Effect.tryPromise(ready))).then((sealed) => {
64
+ if (Result.isFailure(sealed))
65
+ options.reportFailure();
66
+ });
55
67
  const abuse = workflowWebhookAbuse({
56
68
  ...options.abuse,
57
69
  scope: options.scope,
@@ -70,7 +82,7 @@ export function createWorkflowWebhooks(options) {
70
82
  async deliver(delivery) {
71
83
  if (!(await abuse.bindingAdmission(delivery.bindingId)))
72
84
  return { status: "refused" };
73
- const verified = custody.verification.verify(delivery);
85
+ const verified = await custody.verification.verify(delivery);
74
86
  if (verified.status !== "ok")
75
87
  return { status: "refused" };
76
88
  const body = z
@@ -1,5 +1,5 @@
1
1
  import type { AppSetup } from "@fungi.computer/agar";
2
- import { type OysterTenancy, type ResolvedTenant, type TenantScope } from "./tenant.js";
2
+ import { type OysterTenancy, type ResolvedTenant, type TenantPrincipal, type TenantScope } from "./tenant.js";
3
3
  /**
4
4
  * Cloudflare adapters for git Apps on a standalone Oyster: the GIT binding
5
5
  * over Artifacts, named keys for agents, and signed webhook delivery for App
@@ -14,6 +14,7 @@ import type { Grant } from "@fungi.computer/ear-tag/grants";
14
14
  import { type LiveOysterKey, type OysterKeyCapability } from "./keys.js";
15
15
  import { type OysterAgents } from "./agents.js";
16
16
  import { type ArtifactsNamespace } from "@fungi.computer/burrow";
17
+ import { type SecretSealer } from "./credential-migration-002.js";
17
18
  import { type HostEventSource, type HostRecipientEvent, type RecipientDelivery } from "./event-recipients.js";
18
19
  export type { HostEventSource, HostRecipientEvent, RecipientDelivery, } from "./event-recipients.js";
19
20
  import { type OysterAuth, type OysterCapability, type OysterEnv, type OysterGitHost, type OysterHost } from "./host.js";
@@ -81,6 +82,10 @@ export type SubscriptionCreated = Readonly<{
81
82
  subscription: WebhookSubscription;
82
83
  secret: string;
83
84
  }>;
85
+ /** A host with no configured keyring stores no new signing secret. */
86
+ export type SubscriptionRefused = Readonly<{
87
+ error: "unavailable";
88
+ }>;
84
89
  /** One delivery attempt record. */
85
90
  export type WebhookDelivery = Readonly<{
86
91
  id: string;
@@ -95,10 +100,14 @@ export type WebhookDelivery = Readonly<{
95
100
  * The tenant's App event delivery owner: webhook subscriptions with signed,
96
101
  * retried deliveries, and host recipients with durable per-recipient records.
97
102
  * An emit commits here and returns; every delivery happens on the alarm.
103
+ * Signing secrets rest only in this object's S1 envelope.
98
104
  */
99
105
  export declare class OysterWebhooks<Env extends OysterKeysEnv = OysterKeysEnv> extends DurableObject<Env> {
100
106
  #private;
101
107
  constructor(ctx: DurableObjectState, env: Env);
108
+ /** The host's S1 sealer for this object; none means no keyring is configured. */
109
+ protected credentialSealer(): SecretSealer | undefined;
110
+ private secrets;
102
111
  /**
103
112
  * A root that names host recipients delivers to them here. This host has
104
113
  * none, so a row that names one fails rather than claiming delivery.
@@ -117,7 +126,7 @@ export declare class OysterWebhooks<Env extends OysterKeysEnv = OysterKeysEnv> e
117
126
  url: string;
118
127
  types: readonly string[];
119
128
  secret?: string | undefined;
120
- }): SubscriptionCreated;
129
+ }): Promise<SubscriptionCreated | SubscriptionRefused>;
121
130
  /** Every subscription. */
122
131
  subscriptions(): WebhookSubscription[];
123
132
  /** Remove a subscription and its deliveries. */
@@ -216,10 +225,7 @@ export type OysterGitWorkerOptions<Env extends OysterGitWorkerEnv> = Readonly<{
216
225
  * workspace, but whether that key's owner is still this tenant's live
217
226
  * owner is this one port's job, never reimplemented against `env.KEYS`.
218
227
  */
219
- workspace?: (env: Env, keysLive: OysterKeysLivePort, scope: TenantScope, request?: Readonly<{
220
- request: Request;
221
- auth: OysterAuth;
222
- }>) => OysterWorkspace | Promise<OysterWorkspace>;
228
+ workspace?: (env: Env, keysLive: OysterKeysLivePort, scope: TenantScope, caller?: OysterWorkspaceCaller) => OysterWorkspace | Promise<OysterWorkspace>;
223
229
  /** Additional capabilities share the exact workspace selected for the base host. */
224
230
  capabilities?: (env: Env, workspace: OysterWorkspace) => readonly OysterCapability[];
225
231
  /** Admit a presented Workflow Git credential for one repository and scope;
@@ -238,6 +244,16 @@ export type OysterGitWorkerOptions<Env extends OysterGitWorkerEnv> = Readonly<{
238
244
  export type OysterGitWorkerHost = OysterHost & Readonly<{
239
245
  git: OysterGitHost;
240
246
  }>;
247
+ /**
248
+ * Who a workspace is selected for: an HTTP request it may authenticate, or a
249
+ * principal already admitted elsewhere (an MCP catalog).
250
+ */
251
+ export type OysterWorkspaceCaller = Readonly<{
252
+ request: Request;
253
+ auth: OysterAuth;
254
+ }> | Readonly<{
255
+ principal: TenantPrincipal;
256
+ }>;
241
257
  /**
242
258
  * `host.keys.live`'s own shape: the live facts behind a key id, re-checked
243
259
  * against the tenant's current owner on every read; null for an unknown,
@@ -251,7 +267,7 @@ export type OysterGitRoot<Env extends OysterGitWorkerEnv> = Readonly<{
251
267
  /** Select a request's tenant once; `hostFor` reuses that admission for the same request. */
252
268
  admit(env: Env, request: Request): Promise<ResolvedTenant | null>;
253
269
  /** One pinned tenant's host. HTTP, MCP, Agents, Workflows and background wakes all reach it here. */
254
- hostFor(env: Env, scope: TenantScope, request?: Request): Promise<OysterGitWorkerHost>;
270
+ hostFor(env: Env, scope: TenantScope, request?: Request, principal?: TenantPrincipal): Promise<OysterGitWorkerHost>;
255
271
  }>;
256
272
  /** Compose a Git Worker's root from its one options value. */
257
273
  export declare function oysterGitRoot<Env extends OysterGitWorkerEnv>(options: OysterGitWorkerOptions<Env>): OysterGitRoot<Env>;
@@ -282,7 +298,7 @@ export declare function oysterWorkerGit<Env extends OysterGitWorkerEnv>(env: Env
282
298
  * One selected tenant's whole host from a root's options. Roots reach it through
283
299
  * `oysterGitRoot(options).hostFor`; a cold directory passes its own resolved tenant.
284
300
  */
285
- export declare function oysterGitWorkerHost<Env extends OysterGitWorkerEnv>(env: Env, options: OysterGitWorkerOptions<Env>, selected: ResolvedTenant, request?: Request): Promise<OysterGitWorkerHost>;
301
+ export declare function oysterGitWorkerHost<Env extends OysterGitWorkerEnv>(env: Env, options: OysterGitWorkerOptions<Env>, selected: ResolvedTenant, request?: Request, principal?: TenantPrincipal): Promise<OysterGitWorkerHost>;
286
302
  /**
287
303
  * A Git host's whole owner table: keys and webhooks, the root's own owner
288
304
  * routes, and Agent approval and MCP server custody. The host and the