@fungi.computer/oyster 0.57.0 → 0.57.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.
@@ -136,6 +136,23 @@ export declare class OysterWebhooks<Env extends OysterKeysEnv = OysterKeysEnv> e
136
136
  types: readonly string[];
137
137
  secret?: string | undefined;
138
138
  }): Promise<SubscriptionCreated | SubscriptionRefused>;
139
+ /**
140
+ * Replace a subscription's signing secret and return the new one once. The
141
+ * secret it replaces keeps signing beside it for 24 hours, so a receiver
142
+ * can switch without dropping a delivery; a second rotation in that window
143
+ * retires the older one at once. `null` when there is no such subscription;
144
+ * a concurrent change while sealing returns `conflict`.
145
+ */
146
+ rotateSecret(id: string): Promise<Readonly<{
147
+ secret: string;
148
+ }> | Readonly<{
149
+ error: "unavailable" | "conflict";
150
+ }> | null>;
151
+ /**
152
+ * Queue a delivery that ran out of retries again, from its first attempt.
153
+ * Only a `failed` delivery is redelivered; `false` for any other.
154
+ */
155
+ redeliver(deliveryId: string): Promise<boolean>;
139
156
  /** Every subscription. */
140
157
  subscriptions(): WebhookSubscription[];
141
158
  /** Remove a subscription and its deliveries. */
@@ -248,6 +265,8 @@ export type OysterGitWorkerOptions<Env extends OysterGitWorkerEnv> = Readonly<{
248
265
  }> | null>;
249
266
  /** Further owner-only routes this host serves, after the owner guard. */
250
267
  ownerRoutes?: (env: Env, scope: TenantScope) => Routes<OysterEnv>;
268
+ /** Serve the owner's port preview confirm page; see `OysterHost.portPreviewEntry`. */
269
+ portPreviewEntry?: boolean;
251
270
  }>;
252
271
  /** A tenant's whole Git host: the App server, `host.git` and the owner routes. */
253
272
  export type OysterGitWorkerHost = OysterHost & Readonly<{
@@ -498,6 +498,8 @@ const RETRY_DELAYS_MS = [10_000, 60_000, 300_000, 1_800_000, 7_200_000];
498
498
  const HELD_RECHECK_MS = 60_000;
499
499
  /** A held delivery fails after this long, so held rows cannot pile up forever. */
500
500
  const HOLD_LIMIT_MS = 7 * 24 * 60 * 60 * 1000;
501
+ /** How long a rotated-out signing secret still signs, beside the new one. */
502
+ const ROTATION_OVERLAP_MS = 24 * 60 * 60 * 1000;
501
503
  /**
502
504
  * A keyring fault is the host's configuration, not the receiver's: the
503
505
  * delivery waits for it without counting attempts, so none is lost.
@@ -534,7 +536,8 @@ const columnNames = Schema.Array(Schema.Struct({ name: Schema.String }));
534
536
  function ensureSubscriptions(sql) {
535
537
  sql.exec(`CREATE TABLE IF NOT EXISTS oyster_subscriptions (
536
538
  id TEXT PRIMARY KEY, installation_id TEXT NOT NULL, url TEXT NOT NULL, sealed_secret TEXT NOT NULL,
537
- types TEXT NOT NULL, created_at INTEGER NOT NULL) STRICT`);
539
+ types TEXT NOT NULL, created_at INTEGER NOT NULL, previous_sealed_secret TEXT,
540
+ previous_expires_at INTEGER) STRICT`);
538
541
  }
539
542
  const legacySubscription = Schema.Struct({
540
543
  id: Schema.String,
@@ -579,6 +582,10 @@ async function openSigningSecret(sealer, subscription, sealed) {
579
582
  return { kind: "held", reason: "keyring-unknown-key" };
580
583
  return { kind: "unopened" };
581
584
  }
585
+ /** A new Standard Webhooks signing secret: `whsec_` and 24 random bytes. */
586
+ function newSigningSecret() {
587
+ return `whsec_${btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(24))))}`;
588
+ }
582
589
  function toSubscription(row) {
583
590
  const decoded = Schema.decodeUnknownSync(subscriptionRow)(row);
584
591
  return {
@@ -601,6 +608,15 @@ export class OysterWebhooks extends DurableObject {
601
608
  constructor(ctx, env) {
602
609
  super(ctx, env);
603
610
  ensureSubscriptions(ctx.storage.sql);
611
+ // An older Oyster's subscriptions have no rotation columns; they read as
612
+ // never rotated and keep their one secret.
613
+ const subscriptionColumns = Schema.decodeUnknownSync(columnNames)(ctx.storage.sql.exec("PRAGMA table_info(oyster_subscriptions)").toArray()).map(({ name }) => name);
614
+ for (const [column, type] of [
615
+ ["previous_sealed_secret", "TEXT"],
616
+ ["previous_expires_at", "INTEGER"],
617
+ ])
618
+ if (!subscriptionColumns.includes(column))
619
+ ctx.storage.sql.exec(`ALTER TABLE oyster_subscriptions ADD COLUMN ${column} ${type}`);
604
620
  ctx.storage.sql.exec(`
605
621
  CREATE TABLE IF NOT EXISTS oyster_deliveries (
606
622
  id TEXT PRIMARY KEY, subscription TEXT NOT NULL, type TEXT NOT NULL, body TEXT NOT NULL,
@@ -667,8 +683,7 @@ export class OysterWebhooks extends DurableObject {
667
683
  }
668
684
  /** Subscribe `url` to an installation's events; returns the secret once. */
669
685
  async subscribe(input) {
670
- const secret = input.secret ??
671
- `whsec_${btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(24))))}`;
686
+ const secret = input.secret ?? newSigningSecret();
672
687
  const subscription = {
673
688
  id: webhookIds.subscription.generate(),
674
689
  installationId: input.installationId,
@@ -693,6 +708,56 @@ export class OysterWebhooks extends DurableObject {
693
708
  this.ctx.storage.sql.exec("INSERT INTO oyster_subscriptions (id, installation_id, url, sealed_secret, types, created_at) VALUES (?, ?, ?, ?, ?, ?)", subscription.id, subscription.installationId, subscription.url, sealed, JSON.stringify(subscription.types), subscription.createdAt);
694
709
  return { subscription, secret };
695
710
  }
711
+ /**
712
+ * Replace a subscription's signing secret and return the new one once. The
713
+ * secret it replaces keeps signing beside it for 24 hours, so a receiver
714
+ * can switch without dropping a delivery; a second rotation in that window
715
+ * retires the older one at once. `null` when there is no such subscription;
716
+ * a concurrent change while sealing returns `conflict`.
717
+ */
718
+ async rotateSecret(id) {
719
+ try {
720
+ const { sealer, ready } = this.secrets();
721
+ // A restored pre-002 store must be sealed before its first rotation reads it.
722
+ await ready();
723
+ this.#forgetExpiredSecret(id);
724
+ const current = this.ctx.storage.sql
725
+ .exec("SELECT sealed_secret FROM oyster_subscriptions WHERE id = ?", id)
726
+ .toArray()[0];
727
+ if (current === undefined)
728
+ return null;
729
+ if (sealer === undefined)
730
+ throw new CredentialError("unavailable");
731
+ const secret = newSigningSecret();
732
+ const sealed = await sealer.seal(subscriptionContext(id), secret);
733
+ const rotated = this.ctx.storage.sql.exec("UPDATE oyster_subscriptions SET sealed_secret = ?, previous_sealed_secret = ?, previous_expires_at = ? WHERE id = ? AND sealed_secret = ?", sealed, current.sealed_secret, Date.now() + ROTATION_OVERLAP_MS, id, current.sealed_secret).rowsWritten;
734
+ // Removed or rotated by another call while this one sealed.
735
+ return rotated === 0 ? { error: "conflict" } : { secret };
736
+ }
737
+ catch (cause) {
738
+ if (cause instanceof CredentialError && cause.code === "unavailable")
739
+ return { error: "unavailable" };
740
+ throw cause;
741
+ }
742
+ }
743
+ /**
744
+ * Drop a rotated-out secret whose overlap has ended. Checked when a
745
+ * delivery signs or the secret rotates, so no timer is needed.
746
+ */
747
+ #forgetExpiredSecret(id) {
748
+ this.ctx.storage.sql.exec("UPDATE oyster_subscriptions SET previous_sealed_secret = NULL, previous_expires_at = NULL WHERE id = ? AND previous_expires_at <= ?", id, Date.now());
749
+ }
750
+ /**
751
+ * Queue a delivery that ran out of retries again, from its first attempt.
752
+ * Only a `failed` delivery is redelivered; `false` for any other.
753
+ */
754
+ async redeliver(deliveryId) {
755
+ const now = Date.now();
756
+ const reset = this.ctx.storage.sql.exec("UPDATE oyster_deliveries SET state = 'pending', attempts = 0, next_at = ?, last_status = NULL, held_reason = NULL, held_since = NULL, updated_at = ? WHERE id = ? AND state = 'failed'", now, now, deliveryId).rowsWritten > 0;
757
+ if (reset)
758
+ await this.wakeBy(now);
759
+ return reset;
760
+ }
696
761
  /** Every subscription. */
697
762
  subscriptions() {
698
763
  return this.ctx.storage.sql
@@ -760,8 +825,9 @@ export class OysterWebhooks extends DurableObject {
760
825
  .exec("SELECT id, subscription, type, body, attempts, held_since FROM oyster_deliveries WHERE state = 'pending' AND next_at <= ? ORDER BY next_at LIMIT 25", now)
761
826
  .toArray();
762
827
  await Promise.all(due.map(async (delivery) => {
828
+ this.#forgetExpiredSecret(delivery.subscription);
763
829
  const target = this.ctx.storage.sql
764
- .exec("SELECT url, sealed_secret FROM oyster_subscriptions WHERE id = ?", delivery.subscription)
830
+ .exec("SELECT url, sealed_secret, previous_sealed_secret, previous_expires_at FROM oyster_subscriptions WHERE id = ?", delivery.subscription)
765
831
  .toArray()[0];
766
832
  const secret = target === undefined
767
833
  ? undefined
@@ -773,7 +839,19 @@ export class OysterWebhooks extends DurableObject {
773
839
  }
774
840
  let status = null;
775
841
  if (target !== undefined && secret?.kind === "open") {
776
- const attempt = await attemptWebhook({ url: target.url, secret: secret.secret }, delivery);
842
+ // A rotated-out secret signs too until its overlap ends; one that
843
+ // no longer opens is dropped rather than failing the delivery.
844
+ const previous = target.previous_sealed_secret !== null &&
845
+ (target.previous_expires_at ?? 0) > now
846
+ ? await openSigningSecret(sealer, delivery.subscription, target.previous_sealed_secret)
847
+ : undefined;
848
+ const attempt = await attemptWebhook(previous?.kind === "open"
849
+ ? {
850
+ url: target.url,
851
+ secret: secret.secret,
852
+ previousSecret: previous.secret,
853
+ }
854
+ : { url: target.url, secret: secret.secret }, delivery);
777
855
  status = attempt.kind === "response" ? attempt.status : null;
778
856
  }
779
857
  const attempts = delivery.attempts + 1;
@@ -958,6 +1036,19 @@ export function gitAdminRoutes(env, scope) {
958
1036
  });
959
1037
  routes.get("/api/webhooks", owner, async () => Response.json(await env.WEBHOOKS.getByName(scope.durableName("webhooks")).subscriptions()));
960
1038
  routes.get("/api/webhooks/:id/deliveries", owner, async (context) => Response.json(await env.WEBHOOKS.getByName(scope.durableName("webhooks")).deliveries(context.req.param("id"))));
1039
+ routes.post("/api/webhooks/:id/rotate", owner, async (context) => {
1040
+ const rotated = await env.WEBHOOKS.getByName(scope.durableName("webhooks")).rotateSecret(context.req.param("id"));
1041
+ if (rotated === null)
1042
+ return Response.json({ error: "Not found" }, { status: 404 });
1043
+ return "error" in rotated
1044
+ ? Response.json(rotated, {
1045
+ status: rotated.error === "conflict" ? 409 : 503,
1046
+ })
1047
+ : Response.json(rotated);
1048
+ });
1049
+ routes.post("/api/webhooks/deliveries/:id/redeliver", owner, async (context) => (await env.WEBHOOKS.getByName(scope.durableName("webhooks")).redeliver(context.req.param("id")))
1050
+ ? new Response(null, { status: 202 })
1051
+ : Response.json({ error: "No failed delivery with that id" }, { status: 404 }));
961
1052
  routes.delete("/api/webhooks/:id", owner, async (context) => (await env.WEBHOOKS.getByName(scope.durableName("webhooks")).unsubscribe(context.req.param("id")))
962
1053
  ? new Response(null, { status: 204 })
963
1054
  : Response.json({ error: "Not found" }, { status: 404 }));
@@ -1292,6 +1383,8 @@ export async function oysterGitWorkerHost(env, options, selected, request, princ
1292
1383
  };
1293
1384
  if (options.pageScript !== undefined)
1294
1385
  host = { ...host, pageScript: options.pageScript };
1386
+ if (options.portPreviewEntry === true)
1387
+ host = { ...host, portPreviewEntry: true };
1295
1388
  if (options.workflows !== undefined)
1296
1389
  host = { ...host, workflows: options.workflows(env, host) };
1297
1390
  if (options.computerControl !== undefined)
@@ -359,6 +359,15 @@ flowchart LR
359
359
  Instance's `onGitPush` when the Release declares `receives: ["git.push"]`. The
360
360
  App emits typed events through `env.EVENTS`, which Oyster delivers as signed
361
361
  Standard Webhooks and as Workflow triggers on hosts with Workflows.
362
+ `POST /api/webhooks/:id/rotate` returns a new signing secret once; for 24
363
+ hours `webhook-signature` carries both signatures, so a Standard Webhooks
364
+ receiver can switch without a gap. The legacy `x-hub-signature-256` header
365
+ switches to the new secret immediately at rotation. Concurrent rotations
366
+ return HTTP 409 for the losing request. A delivery that ran out of retries is
367
+ `failed`, and `POST /api/webhooks/deliveries/:id/redeliver` queues it again
368
+ with the same delivery ID. Repeated requests while it is pending or delivered
369
+ do not queue another delivery. Upgrades retain existing subscriptions and
370
+ queued deliveries.
362
371
 
363
372
  An App's own `GIT` binding (`await env.GIT.cloneUrl(repo)`, create, fork, log,
364
373
  read and merge) uses `admitted.binding(onBehalfOf)`. Its writes skip the App's
package/docs/api/git.md CHANGED
@@ -449,20 +449,26 @@ function webhookHeaders(
449
449
  type,
450
450
  timestamp,
451
451
  body,
452
+ previousSecret?,
452
453
  ): Promise<Record<string, string>>;
453
454
  ```
454
455
 
455
456
  Headers for one signed delivery: Standard Webhooks plus `X-Hub-Signature-256`.
457
+ While a rotated-out secret is still honoured, `previousSecret` adds its
458
+ signature after the current one, space-separated as Standard Webhooks allows, so
459
+ a receiver holding either secret verifies the delivery. `X-Hub-Signature-256`
460
+ uses only the current secret and switches at rotation.
456
461
 
457
462
  #### Parameters
458
463
 
459
- | Parameter | Type |
460
- | ----------- | -------- |
461
- | `secret` | `string` |
462
- | `id` | `string` |
463
- | `type` | `string` |
464
- | `timestamp` | `number` |
465
- | `body` | `string` |
464
+ | Parameter | Type |
465
+ | ----------------- | -------- |
466
+ | `secret` | `string` |
467
+ | `id` | `string` |
468
+ | `type` | `string` |
469
+ | `timestamp` | `number` |
470
+ | `body` | `string` |
471
+ | `previousSecret?` | `string` |
466
472
 
467
473
  #### Returns
468
474
 
package/docs/api/host.md CHANGED
@@ -520,6 +520,7 @@ type OysterHost = Readonly<{
520
520
  mcp?: OysterMcp;
521
521
  git?: OysterGitHost;
522
522
  ownerRoutes?: Routes<OysterEnv>;
523
+ portPreviewEntry?: boolean;
523
524
  capabilities?: readonly OysterCapability[];
524
525
  workbench?: Readonly<{
525
526
  directory: Promise<Readonly<{
@@ -353,6 +353,55 @@ Subscribe `url` to an installation's events; returns the secret once.
353
353
  [`WebhookSubscription`](#webhooksubscription); `secret`: `string`; \}\> \|
354
354
  `Readonly`\<\{ `error`: `"unavailable"`; \}\>\>
355
355
 
356
+ ##### rotateSecret()
357
+
358
+ ```ts
359
+ rotateSecret(id): Promise<
360
+ | Readonly<{
361
+ secret: string;
362
+ }>
363
+ | Readonly<{
364
+ error: "unavailable" | "conflict";
365
+ }>
366
+ | null>;
367
+ ```
368
+
369
+ Replace a subscription's signing secret and return the new one once. The secret
370
+ it replaces keeps signing beside it for 24 hours, so a receiver can switch
371
+ without dropping a delivery; a second rotation in that window retires the older
372
+ one at once. `null` when there is no such subscription; a concurrent change
373
+ while sealing returns `conflict`.
374
+
375
+ ###### Parameters
376
+
377
+ | Parameter | Type |
378
+ | --------- | -------- |
379
+ | `id` | `string` |
380
+
381
+ ###### Returns
382
+
383
+ `Promise`\< \| `Readonly`\<\{ `secret`: `string`; \}\> \| `Readonly`\<\{
384
+ `error`: `"unavailable"` \| `"conflict"`; \}\> \| `null`\>
385
+
386
+ ##### redeliver()
387
+
388
+ ```ts
389
+ redeliver(deliveryId): Promise<boolean>;
390
+ ```
391
+
392
+ Queue a delivery that ran out of retries again, from its first attempt. Only a
393
+ `failed` delivery is redelivered; `false` for any other.
394
+
395
+ ###### Parameters
396
+
397
+ | Parameter | Type |
398
+ | ------------ | -------- |
399
+ | `deliveryId` | `string` |
400
+
401
+ ###### Returns
402
+
403
+ `Promise`\<`boolean`\>
404
+
356
405
  ##### subscriptions()
357
406
 
358
407
  ```ts
@@ -1714,6 +1763,7 @@ type OysterGitWorkerOptions<Env> = Readonly<{
1714
1763
  }
1715
1764
  > | null>;
1716
1765
  ownerRoutes?: (env, scope) => Routes<OysterEnv>;
1766
+ portPreviewEntry?: boolean;
1717
1767
  }>;
1718
1768
  ```
1719
1769