@fungi.computer/oyster 0.56.2 → 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.
Files changed (62) hide show
  1. package/dist/agent-computer-source.js +4 -1
  2. package/dist/auth.d.ts +12 -4
  3. package/dist/auth.js +85 -24
  4. package/dist/boot-capability-route.js +5 -1
  5. package/dist/boot-gate.d.ts +5 -0
  6. package/dist/boot-gate.js +12 -2
  7. package/dist/boot-host-script.js +1 -1
  8. package/dist/boot-mount.d.ts +7 -1
  9. package/dist/boot-mount.js +11 -5
  10. package/dist/credential-migration-002.js +6 -1
  11. package/dist/embed-metafiles.js +2 -2
  12. package/dist/embed-scripts.js +2 -2
  13. package/dist/git.d.ts +8 -2
  14. package/dist/git.js +12 -3
  15. package/dist/hello-app-script.js +1 -1
  16. package/dist/host-page-assets.js +1 -1
  17. package/dist/host-page-lazy.d.ts +2 -0
  18. package/dist/host-page-lazy.js +8 -0
  19. package/dist/host-page.d.ts +22 -1
  20. package/dist/host-page.js +91 -12
  21. package/dist/host.d.ts +8 -0
  22. package/dist/host.js +60 -7
  23. package/dist/owner-sessions.d.ts +25 -0
  24. package/dist/owner-sessions.js +50 -0
  25. package/dist/page/boot-host.js +20 -2
  26. package/dist/page/port-preview.d.ts +1 -0
  27. package/dist/page/port-preview.js +33 -0
  28. package/dist/page-script.js +3 -3
  29. package/dist/platform-skills.generated.d.ts +1 -1
  30. package/dist/platform-skills.generated.js +1 -1
  31. package/dist/port-preview-entry.d.ts +84 -0
  32. package/dist/port-preview-entry.js +86 -0
  33. package/dist/standalone/agents.js +1 -0
  34. package/dist/standalone/builds.js +5 -0
  35. package/dist/standalone/candidate-preview.d.ts +25 -0
  36. package/dist/standalone/candidate-preview.js +265 -0
  37. package/dist/standalone/computer.d.ts +2 -3
  38. package/dist/standalone/computer.js +13 -9
  39. package/dist/standalone/preview.d.ts +9 -4
  40. package/dist/standalone/preview.js +35 -44
  41. package/dist/standalone/tenancy.d.ts +1 -1
  42. package/dist/standalone/tenancy.js +9 -1
  43. package/dist/standalone/worker.js +15 -2
  44. package/dist/starter-agent.js +5 -2
  45. package/dist/storage-frame.d.ts +3 -3
  46. package/dist/tenancy/owner-key.d.ts +4 -1
  47. package/dist/tenancy/owner-key.js +27 -2
  48. package/dist/upgrade/old-worker-http.js +2 -6
  49. package/dist/webhook-delivery.d.ts +1 -0
  50. package/dist/webhook-delivery.js +1 -1
  51. package/dist/workers-git.d.ts +19 -0
  52. package/dist/workers-git.js +108 -7
  53. package/dist/workers.d.ts +11 -0
  54. package/dist/workers.js +33 -1
  55. package/docs/api/README.md +14 -3
  56. package/docs/api/auth.md +96 -8
  57. package/docs/api/git.md +13 -7
  58. package/docs/api/host.md +2 -0
  59. package/docs/api/tenancy/owner-key.md +1 -0
  60. package/docs/api/workers-git.md +50 -0
  61. package/docs/api/workers.md +98 -16
  62. package/package.json +18 -18
@@ -31,7 +31,7 @@ import { credentialMigration002, } from "./credential-migration-002.js";
31
31
  import { createRecipientDeliveries, } from "./event-recipients.js";
32
32
  import { createOyster, } from "./host.js";
33
33
  import { oysterPrincipalIsOwner, owner as ownerRoute, routes as routeTable, } from "./authorization.js";
34
- import { OysterInstance, oysterBindingEntrypoint, oysterBindings, oysterWorkerHost, r2FileSource, r2ArtifactStore, serveOysterBootCapability, } from "./workers.js";
34
+ import { OysterInstance, oysterBindingEntrypoint, oysterBindings, oysterWorkerHost, r2FileSource, r2ArtifactStore, registryOwnerSessions, serveOysterBootCapability, } from "./workers.js";
35
35
  import { registryInstallations } from "./internal/registry-installations.js";
36
36
  import { refuseOlderOysterStore } from "./older-oyster-store-refusal.js";
37
37
  const infoSchema = Schema.Struct({
@@ -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 }));
@@ -1006,7 +1097,7 @@ export function oysterGitRoot(options) {
1006
1097
  /** The single-owner root's tenancy: the owner key or a named key, at the configured origin only. */
1007
1098
  export function ownerOrKeyTenancy(env) {
1008
1099
  const scope = tenantScope(defaultTenant, env.OYSTER_ORIGIN);
1009
- return implicitTenancy(scope.origin, ownerOrKeyAuth(env.OYSTER_OWNER_KEY, env.OYSTER_OWNER_NAME ?? "owner", () => env.KEYS.getByName(scope.durableName("keys"))));
1100
+ return implicitTenancy(scope.origin, ownerOrKeyAuth(env.OYSTER_OWNER_KEY, env.OYSTER_OWNER_NAME ?? "owner", registryOwnerSessions(() => env.REGISTRY.getByName(scope.durableName("registry"))), () => env.KEYS.getByName(scope.durableName("keys"))));
1010
1101
  }
1011
1102
  /** The standalone Worker's `fetch` handler with the git door and owner routes. */
1012
1103
  export function createOysterGitWorker(root) {
@@ -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)
@@ -1355,6 +1448,14 @@ function pinnedTenantAuth(tenancy, scope, admissions, authentications) {
1355
1448
  return (current.auth.login?.(incoming) ??
1356
1449
  new Response("Sign-in is not available", { status: 404 }));
1357
1450
  },
1451
+ logout: async (incoming) => {
1452
+ const current = await admitted(incoming);
1453
+ if (current?.scope.tenantId !== scope.tenantId ||
1454
+ current.scope.origin !== scope.origin)
1455
+ return new Response("Not found", { status: 404 });
1456
+ return (current.auth.logout?.(incoming) ??
1457
+ new Response("Sign-out is not available", { status: 404 }));
1458
+ },
1358
1459
  };
1359
1460
  }
1360
1461
  /** Deploy the MCP owner from the same root as createOysterGitWorker. */
package/dist/workers.d.ts CHANGED
@@ -14,6 +14,7 @@ import { type BackgroundSyncRefusal } from "@fungi.computer/puffball/background-
14
14
  import { type TenantScope, type TenantId } from "./tenant.js";
15
15
  import { type GillCall, type GillReply } from "@fungi.computer/gills";
16
16
  import { ownerKeyAuth } from "./auth.js";
17
+ import { type OwnerSessions } from "./owner-sessions.js";
17
18
  import type { AppGitPushFact, GitBinding, GitPushQuestion, GitPushVerdict } from "@fungi.computer/agar/git";
18
19
  import { type OysterMcpOwner } from "./mcp-owner.js";
19
20
  export { createOysterMcpOwner, OysterMcpOwner, type OysterMcpOwnerEnv, type OysterMcpTenantPin, } from "./mcp-owner.js";
@@ -89,6 +90,14 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
89
90
  #private;
90
91
  /** The plain root has the same single owner-key host as OysterInstance. */
91
92
  protected hostFor(scope: TenantScope): Promise<OysterHost>;
93
+ /** This tenant's owner browser sessions; only the Worker's owner sign-in calls these. */
94
+ private ownerSessions;
95
+ /** Open an owner browser session from its digest; see `OwnerSessions.open`. */
96
+ openOwnerSession(owner: string, digest: string, now: number): Promise<void>;
97
+ /** The owner a live session signs in, or null. */
98
+ ownerSessionOwner(digest: string, now: number): Promise<string | null>;
99
+ /** Revoke one owner browser session. */
100
+ revokeOwnerSession(digest: string): Promise<void>;
92
101
  /** Trusted host RPC; an operation input cannot select actor, namespace or tenant. */
93
102
  approvalSubmit(pin: Readonly<{
94
103
  tenantId: string;
@@ -503,6 +512,8 @@ export declare function oysterWorkerHost(env: OysterWorkerEnv, auth: OysterAuth,
503
512
  workspace?: OysterWorkspace;
504
513
  scope?: TenantScope;
505
514
  }>): OysterHost;
515
+ /** A tenant registry's owner sessions as the `OwnerSessions` port. */
516
+ export declare function registryOwnerSessions(registry: () => Pick<OysterRegistry, "openOwnerSession" | "ownerSessionOwner" | "revokeOwnerSession">): OwnerSessions;
506
517
  declare const OysterMcp_base: new (ctx: DurableObjectState, env: Readonly<{
507
518
  /** Cloudflare Browser Run binding for the UI boot check and the agent browser. */
508
519
  BROWSER?: Readonly<{
package/dist/workers.js CHANGED
@@ -27,6 +27,7 @@ import { defaultTenant, tenantIdSchema, tenantScope, } from "./tenant.js";
27
27
  import { decodeGillReply, } from "@fungi.computer/gills";
28
28
  import { causeClass, failureDiagnostic } from "./cause-class.js";
29
29
  import { ownerKeyAuth } from "./auth.js";
30
+ import { ownerSessionStore } from "./owner-sessions.js";
30
31
  import { createOysterMcpOwner, remoteOysterMcp, } from "./mcp-owner.js";
31
32
  export { createOysterMcpOwner, OysterMcpOwner, } from "./mcp-owner.js";
32
33
  import { guestLimits } from "./guest-policy.js";
@@ -82,6 +83,24 @@ export class OysterRegistry extends DurableObject {
82
83
  hostFor(scope) {
83
84
  return Promise.resolve(ownerKeyRootHost(this.env, { scope }));
84
85
  }
86
+ #ownerSessions;
87
+ /** This tenant's owner browser sessions; only the Worker's owner sign-in calls these. */
88
+ ownerSessions() {
89
+ this.#ownerSessions ??= ownerSessionStore(this.ctx.storage.sql);
90
+ return this.#ownerSessions;
91
+ }
92
+ /** Open an owner browser session from its digest; see `OwnerSessions.open`. */
93
+ openOwnerSession(owner, digest, now) {
94
+ return this.ownerSessions().open(owner, digest, now);
95
+ }
96
+ /** The owner a live session signs in, or null. */
97
+ ownerSessionOwner(digest, now) {
98
+ return this.ownerSessions().owner(digest, now);
99
+ }
100
+ /** Revoke one owner browser session. */
101
+ revokeOwnerSession(digest) {
102
+ return this.ownerSessions().revoke(digest);
103
+ }
85
104
  /** Trusted host RPC; an operation input cannot select actor, namespace or tenant. */
86
105
  approvalSubmit(pin, call) {
87
106
  return this.approvalHome(pin).submit(call);
@@ -1492,7 +1511,20 @@ export function oysterWorkerHost(env, auth, options = {}) {
1492
1511
  * stores. Its HTTP Worker, MCP owner and background wakes all compose here.
1493
1512
  */
1494
1513
  function ownerKeyRootHost(env, options) {
1495
- return oysterWorkerHost(env, ownerKeyAuth(env.OYSTER_OWNER_KEY), options);
1514
+ const scope = options.scope ?? tenantScope(defaultTenant, env.OYSTER_ORIGIN);
1515
+ return oysterWorkerHost(env, ownerKeyAuth(env.OYSTER_OWNER_KEY, "owner", registryOwnerSessions(() => env.REGISTRY.getByName(scope.durableName("registry")))), options);
1516
+ }
1517
+ /** A tenant registry's owner sessions as the `OwnerSessions` port. */
1518
+ export function registryOwnerSessions(registry) {
1519
+ return {
1520
+ open: async (owner, digest, now) => {
1521
+ await registry().openOwnerSession(owner, digest, now);
1522
+ },
1523
+ owner: async (digest, now) => await registry().ownerSessionOwner(digest, now),
1524
+ revoke: async (digest) => {
1525
+ await registry().revokeOwnerSession(digest);
1526
+ },
1527
+ };
1496
1528
  }
1497
1529
  /** The non-git standalone root's MCP owner. */
1498
1530
  export class OysterMcp extends createOysterMcpOwner((env, scope) => ownerKeyRootHost(env, { scope })) {
@@ -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
@@ -581,9 +590,11 @@ reaches an App. `owner("direct")` refuses App-mediated requests, so consent,
581
590
  keys and secrets never ride an App.
582
591
 
583
592
  A browser signs in only with the owner key, through `/login` and its
584
- `SameSite=Strict` session cookie; named keys sign in only by header. Anonymous
585
- requests reach only `/login`, `robots.txt`, digest-pinned shell and App UI bytes
586
- and the website chat.
593
+ `SameSite=Strict` session cookie; named keys sign in only by header. The cookie
594
+ holds a random session id. The tenant registry keeps an HMAC of it, keyed by the
595
+ owner key, with a 30-day expiry; `POST /logout` revokes it, and rotating the
596
+ owner key ends every session. Anonymous requests reach only `/login`,
597
+ `robots.txt`, digest-pinned shell and App UI bytes and the website chat.
587
598
 
588
599
  ### Owner state and selection
589
600
 
package/docs/api/auth.md CHANGED
@@ -8,6 +8,36 @@
8
8
 
9
9
  # auth
10
10
 
11
+ ## Type Aliases
12
+
13
+ ### OwnerSessions
14
+
15
+ ```ts
16
+ type OwnerSessions = Readonly<{
17
+ open: Promise<void>;
18
+ owner: Promise<string | null>;
19
+ revoke: Promise<void>;
20
+ }>;
21
+ ```
22
+
23
+ The server side of owner browser sessions. The cookie carries a random session
24
+ id; the store keeps only its digest, the owner it signs in, and an expiry.
25
+ Logging out revokes the row, so a copied cookie stops working.
26
+
27
+ ---
28
+
29
+ ### OwnerSessionSql
30
+
31
+ ```ts
32
+ type OwnerSessionSql = Readonly<{
33
+ exec: {
34
+ toArray: readonly object[];
35
+ };
36
+ }>;
37
+ ```
38
+
39
+ The synchronous SQL a Durable Object or SQLite host gives the store.
40
+
11
41
  ## Variables
12
42
 
13
43
  ### ownerKeyCookieName
@@ -39,23 +69,60 @@ const lastUsedGranularityMs: number;
39
69
  How stale a key's last-used time may be: calls inside this window do not
40
70
  re-stamp it.
41
71
 
72
+ ---
73
+
74
+ ### ownerSessionLifetimeMs
75
+
76
+ ```ts
77
+ const ownerSessionLifetimeMs: number;
78
+ ```
79
+
80
+ How long one browser sign-in lasts, absolutely: no sliding renewal.
81
+
42
82
  ## Functions
43
83
 
84
+ ### ownerKeyCredential()
85
+
86
+ ```ts
87
+ function ownerKeyCredential(
88
+ ownerKey,
89
+ request,
90
+ ): Promise<"owner" | "refused" | "absent">;
91
+ ```
92
+
93
+ Whether `request` carries the owner key itself, as a Bearer token or a Git
94
+ Basic-auth password. `absent` means it carries neither.
95
+
96
+ #### Parameters
97
+
98
+ | Parameter | Type |
99
+ | ---------- | --------- |
100
+ | `ownerKey` | `string` |
101
+ | `request` | `Request` |
102
+
103
+ #### Returns
104
+
105
+ `Promise`\<`"owner"` \| `"refused"` \| `"absent"`\>
106
+
107
+ ---
108
+
44
109
  ### ownerKeyAuth()
45
110
 
46
111
  ```ts
47
- function ownerKeyAuth(ownerKey, ownerId?): OysterAuth;
112
+ function ownerKeyAuth(ownerKey, ownerId, sessions): OysterAuth;
48
113
  ```
49
114
 
50
- Single-owner sign-in: a bearer token, a Git Basic-auth password, or a session
51
- cookie holding the owner key's digest. The key is never stored in the browser.
115
+ Single-owner sign-in: a bearer token, a Git Basic-auth password, or a browser
116
+ session. A session is a random id in the cookie; `sessions` keeps its digest,
117
+ owner and expiry, and logging out revokes it.
52
118
 
53
119
  #### Parameters
54
120
 
55
- | Parameter | Type | Default value |
56
- | ---------- | -------- | ------------- |
57
- | `ownerKey` | `string` | `undefined` |
58
- | `ownerId` | `string` | `"owner"` |
121
+ | Parameter | Type |
122
+ | ---------- | --------------------------------- |
123
+ | `ownerKey` | `string` |
124
+ | `ownerId` | `string` |
125
+ | `sessions` | [`OwnerSessions`](#ownersessions) |
59
126
 
60
127
  #### Returns
61
128
 
@@ -66,7 +133,7 @@ cookie holding the owner key's digest. The key is never stored in the browser.
66
133
  ### ownerOrKeyAuth()
67
134
 
68
135
  ```ts
69
- function ownerOrKeyAuth(ownerKey, ownerId, keys): OysterAuth;
136
+ function ownerOrKeyAuth(ownerKey, ownerId, sessions, keys): OysterAuth;
70
137
  ```
71
138
 
72
139
  The owner key, or a named key admitted as its canonical Team-key actor.
@@ -77,8 +144,29 @@ The owner key, or a named key admitted as its canonical Team-key actor.
77
144
  | ---------- | ----------------------------------------------------------------------------------- |
78
145
  | `ownerKey` | `string` |
79
146
  | `ownerId` | `string` |
147
+ | `sessions` | [`OwnerSessions`](#ownersessions) |
80
148
  | `keys` | () => `Pick`\<[`OysterKeyStore`](keys.md#oysterkeystore), `"verify"` \| `"touch"`\> |
81
149
 
82
150
  #### Returns
83
151
 
84
152
  [`OysterAuth`](host.md#oysterauth)
153
+
154
+ ---
155
+
156
+ ### ownerSessionStore()
157
+
158
+ ```ts
159
+ function ownerSessionStore(sql): OwnerSessions;
160
+ ```
161
+
162
+ Owner sessions over one store's SQL.
163
+
164
+ #### Parameters
165
+
166
+ | Parameter | Type |
167
+ | --------- | ------------------------------------- |
168
+ | `sql` | [`OwnerSessionSql`](#ownersessionsql) |
169
+
170
+ #### Returns
171
+
172
+ [`OwnerSessions`](#ownersessions)
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
@@ -183,6 +183,7 @@ type OysterAuth = Readonly<{
183
183
  resolve: (actor) => Promise<TenantPrincipal | null>;
184
184
  authenticate: (request) => Promise<OysterAuthResult>;
185
185
  login?: (request) => Promise<Response>;
186
+ logout?: (request) => Promise<Response>;
186
187
  }>;
187
188
  ```
188
189
 
@@ -519,6 +520,7 @@ type OysterHost = Readonly<{
519
520
  mcp?: OysterMcp;
520
521
  git?: OysterGitHost;
521
522
  ownerRoutes?: Routes<OysterEnv>;
523
+ portPreviewEntry?: boolean;
522
524
  capabilities?: readonly OysterCapability[];
523
525
  workbench?: Readonly<{
524
526
  directory: Promise<Readonly<{
@@ -34,6 +34,7 @@ type OwnerKeyOptions = Readonly<{
34
34
  memberId: string;
35
35
  }> | null>;
36
36
  }>;
37
+ sessions: OwnerSessions;
37
38
  login?: Readonly<{
38
39
  resolveTenant: ReadonlyTenancy["resolve"];
39
40
  }>;
@@ -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