@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/workers-git.d.ts

@@ -0,0 +1,285 @@
+import { type OysterTenancy, type ResolvedTenant, type TenantScope } from "./tenant.js";
+/**
+ * Cloudflare adapters for git Apps on a standalone Oyster: the GIT binding
+ * over Artifacts, named keys for agents, and signed webhook delivery for App
+ * events. Every credential and secret stays in these host objects.
+ */
+import { DurableObject } from "cloudflare:workers";
+import { type InvocationFrame } from "./invocation.js";
+import { Hono } from "hono";
+import { type GitBinding } from "@fungi.computer/agar/git";
+import { type GitDoorTarget, type StandardWebhookPayload } from "./git.js";
+import { type KeyStore } from "@fungi.computer/ear-tag/keys";
+import type { Grant } from "@fungi.computer/ear-tag/grants";
+import { type LiveOysterKey, type OysterKeyCapability } from "./keys.js";
+import { type OysterAgents } from "./agents.js";
+import { type ArtifactsNamespace } from "@fungi.computer/burrow";
+import { type HostEventSource, type HostRecipientEvent, type RecipientDelivery } from "./event-recipients.js";
+export type { HostEventSource, HostRecipientEvent, RecipientDelivery, } from "./event-recipients.js";
+import { type OysterCapability, type OysterEnv, type OysterGitHost, type OysterHost } from "./host.js";
+import type { GitWriter } from "@fungi.computer/agar/git";
+import { OysterInstance, type OysterBindingContext, type OysterBindingRow, type OysterBindingTable, type OysterWorkspace, type OysterWorkerEnv, type OysterInvocationHost } from "./workers.js";
+/** The GIT binding plus the credential only the host's git door may use. */
+export type ArtifactsGit = Omit<GitBinding, "cloneUrl"> & Readonly<{
+    /** The provider remote and a credential; never given to the App. */
+    credential(name: string, scope: "read" | "write"): Promise<Readonly<{
+        remote: string;
+        token: string;
+    }>>;
+}>;
+/** The GIT binding over Artifacts for one installation (`prefix` scopes its names).
+ * Credentials remain host-held and are reused until thirty seconds before the
+ * provider expiry or eight minutes, whichever comes first. Every operation still
+ * checks its captured grant. Provider 401/403 discards the credential for remint.
+ */
+export declare function createArtifactsGit(binding: ArtifactsNamespace, prefix: string, grant: Readonly<{
+    operations: readonly string[];
+    /** Recheck the captured host invocation immediately before provider work. */
+    beforeProvider?: () => void;
+}>): ArtifactsGit;
+/**
+ * Named keys an owner issues directly: an Ear Tag key store scoped to this
+ * tenant. A key's id is the name the owner chose for it, so forks and other
+ * name-derived identities (`service.ts:95`) stay stable across a reissue.
+ * Plaintext keys are never stored.
+ */
+export declare class OysterKeys extends DurableObject<OysterKeysEnv> {
+    #private;
+    constructor(ctx: DurableObjectState, env: OysterKeysEnv);
+    /**
+     * Issue a key named `name`, its id too. Refuses `conflict` once a name has
+     * been used, including by a now-revoked key: a name is never reused.
+     */
+    issue(owner: string, input: Readonly<{
+        name: string;
+        grants: readonly Grant<OysterKeyCapability>[];
+        expiresAt?: number;
+    }>): ReturnType<KeyStore<OysterKeyCapability>["issue"]>;
+    /** Revoke a key by id; idempotent on repeat. */
+    revoke(owner: string, requestId: string, keyId: string): ReturnType<KeyStore<OysterKeyCapability>["revoke"]>;
+    /** Every key this tenant has issued, newest first. */
+    list(owner: string): ReturnType<KeyStore<OysterKeyCapability>["list"]>;
+    /** Verify a bearer secret and return its current principal. */
+    verify(secret: string): ReturnType<KeyStore<OysterKeyCapability>["verify"]>;
+    /** The live facts behind one key id, for the host's `keys.live` port; `null` for an unknown, revoked, expired or suspended key. */
+    live(keyId: string): Promise<LiveOysterKey | null>;
+}
+/** Bindings the keys and webhook objects need: none of their own. */
+export type OysterKeysEnv = Readonly<Record<never, never>>;
+/** One webhook subscription for an installation's events. */
+export type WebhookSubscription = Readonly<{
+    id: string;
+    installationId: string;
+    url: string;
+    /** Event types delivered; empty means every type. */
+    types: readonly string[];
+    createdAt: number;
+}>;
+/** A new subscription and its signing secret, shown once. */
+export type SubscriptionCreated = Readonly<{
+    subscription: WebhookSubscription;
+    secret: string;
+}>;
+/** One delivery attempt record. */
+export type WebhookDelivery = Readonly<{
+    id: string;
+    subscription: string;
+    type: string;
+    state: "pending" | "delivered" | "failed";
+    attempts: number;
+    lastStatus: number | null;
+    updatedAt: number;
+}>;
+/**
+ * The tenant's App event delivery owner: webhook subscriptions with signed,
+ * retried deliveries, and host recipients with durable per-recipient records.
+ * An emit commits here and returns; every delivery happens on the alarm.
+ */
+export declare class OysterWebhooks<Env extends OysterKeysEnv = OysterKeysEnv> extends DurableObject<Env> {
+    #private;
+    constructor(ctx: DurableObjectState, env: Env);
+    /**
+     * A root that names host recipients delivers to them here. This host has
+     * none, so a row that names one fails rather than claiming delivery.
+     */
+    protected deliverToRecipient(delivery: Readonly<{
+        recipient: string;
+        event: HostRecipientEvent;
+    }>): Promise<void>;
+    /** Arm the one alarm no later than `at`; webhooks and recipients share it. */
+    private wakeBy;
+    /** Recent deliveries to one host recipient, newest first. */
+    recipientDeliveries(recipient: string): RecipientDelivery[];
+    /** Subscribe `url` to an installation's events; returns the secret once. */
+    subscribe(input: {
+        installationId: string;
+        url: string;
+        types: readonly string[];
+        secret?: string | undefined;
+    }): SubscriptionCreated;
+    /** Every subscription. */
+    subscriptions(): WebhookSubscription[];
+    /** Remove a subscription and its deliveries. */
+    unsubscribe(id: string): boolean;
+    /** Recent deliveries for one subscription, newest first. */
+    deliveries(subscription: string): WebhookDelivery[];
+    /**
+     * Accept an emitted event: queue it for every matching subscription and
+     * every named host recipient (idempotent per event id). Nothing is delivered
+     * before this returns, so no recipient can fail the emitter's write.
+     */
+    enqueue(source: HostEventSource, payload: StandardWebhookPayload, eventId: string, recipients: readonly string[]): Promise<number>;
+    /** Deliver due webhooks and recipient rows, then schedule the next retry. */
+    alarm(): Promise<void>;
+}
+/** Bindings the git adapters read from a standalone Oyster Worker. */
+export type OysterGitEnv = Readonly<{
+    /** The Artifacts Workers binding, where the runtime has one (Cloudflare). */
+    ARTIFACTS?: ArtifactsNamespace;
+    /**
+     * Otherwise Artifacts is reached over its REST API (celld, Node): the
+     * account, the namespace, and an API token secret with Artifacts access.
+     */
+    ARTIFACTS_ACCOUNT_ID?: string;
+    ARTIFACTS_NAMESPACE?: string;
+    ARTIFACTS_API_TOKEN?: string;
+    KEYS: DurableObjectNamespace<OysterKeys>;
+    WEBHOOKS: DurableObjectNamespace<OysterWebhooks>;
+}>;
+/** The Artifacts namespace: the binding when present, else the REST API. */
+export declare function artifactsOf(env: OysterGitEnv): ArtifactsNamespace;
+/**
+ * EVENTS: commit the emit to this tenant's delivery owner and return. Webhook
+ * subscribers and the host recipients a root names are delivered afterwards,
+ * so a subscriber outage never fails the emitting App's write.
+ */
+export declare function eventsBindingFor<Env extends OysterGitWorkerEnv>(recipients: (context: OysterBindingContext<Env>, frame: InvocationFrame<OysterInvocationHost>) => Promise<readonly string[]>): OysterBindingRow<Env>;
+/** EVENTS for a host with webhook subscribers only. */
+export declare const eventsBinding: OysterBindingRow<OysterGitWorkerEnv>;
+/** The plain host's bindings plus native GIT over Artifacts and signed EVENTS. */
+export declare const gitBindings: OysterBindingTable<OysterGitWorkerEnv>;
+declare const OysterBinding_base: abstract new (ctx: ExecutionContext, env: OysterGitWorkerEnv) => CloudflareWorkersModule.WorkerEntrypoint<OysterGitWorkerEnv, Readonly<{
+    instanceId: string;
+    binding: import("@fungi.computer/puffball/app").AppBackendBindingName;
+    frameId: string;
+}>>;
+/** A git Worker's one guest binding entrypoint, over `gitBindings`. */
+export declare class OysterBinding extends OysterBinding_base {
+}
+/** One listed or issued key's owner-facing summary; never its secret or owner id. */
+export type OysterKeySummary = Readonly<{
+    keyId: string;
+    name: string;
+    grants: readonly Grant<OysterKeyCapability>[];
+    expiresAt: number | null;
+    createdAt: number;
+    lastUsedAt: number | null;
+    revokedAt: number | null;
+}>;
+/** Owner routes for keys and webhooks; `createOyster` mounts them owner-only. */
+export declare function gitAdminRoutes(env: OysterGitEnv, scope: TenantScope): Hono<OysterEnv>;
+/** A standalone Oyster Worker that also hosts git Apps. */
+export type OysterGitWorkerEnv = OysterWorkerEnv & OysterGitEnv & Readonly<{
+    /** This Oyster's public origin, for clone URLs (e.g. https://oyster.example). */
+    OYSTER_ORIGIN: string;
+    /** The owner's display name, used as their actor id (default "owner"). */
+    OYSTER_OWNER_NAME?: string;
+}>;
+/**
+ * An App Instance whose backend may also receive declared Git and Events
+ * bindings. Background wakes readmit members through the deployable root's
+ * `hostFor`, the same composition HTTP and MCP use.
+ */
+export declare abstract class OysterGitInstance<Env extends OysterGitWorkerEnv = OysterGitWorkerEnv> extends OysterInstance<Env> {
+    protected readonly bindings: OysterBindingTable<Env>;
+    /** The deployable root's host for one pinned tenant: `root.hostFor(this.env, scope)`. */
+    protected abstract hostFor(scope: TenantScope): OysterHost;
+}
+/**
+ * One deployable Git root's options. Every door (HTTP, MCP, Agents, Workflows,
+ * background wakes) composes its tenant host from this one value through
+ * `oysterGitRoot(options).hostFor`.
+ */
+export type OysterGitWorkerOptions<Env extends OysterGitWorkerEnv> = Readonly<{
+    /** Resolve one host-selected tenant before authentication; unknown origins refuse.
+     * A single-owner root passes `ownerOrKeyTenancy`. */
+    tenancy: (env: Env) => OysterTenancy;
+    /** Select the installed home App in the deployable root, independently of core. */
+    homeInstallationId?: (env: Env) => string;
+    /** Host browser composition; core imports no dashboard App. */
+    pageScript?: string;
+    /** Connect this Worker’s Agent directory and transports. */
+    agents?: (env: Env, scope: TenantScope) => OysterAgents;
+    /**
+     * Select this host's workspace once, before constructing its HTTP and MCP
+     * host. `keysLive` is the same owner-checked port `host.keys.live` uses
+     * below: a key's own `computer.use`-style grant check belongs to the
+     * workspace, but whether that key's owner is still this tenant's live
+     * owner is this one port's job, never reimplemented against `env.KEYS`.
+     */
+    workspace?: (env: Env, keysLive: OysterKeysLivePort) => OysterWorkspace;
+    /** Additional capabilities share the exact workspace selected for the base host. */
+    capabilities?: (env: Env, workspace: OysterWorkspace, keysLive: OysterKeysLivePort) => readonly OysterCapability[];
+    /** Admit a host-minted Workflow Git pass for one repository and scope;
+     * omit when this host mints no Workflow Git passes. */
+    workflowGitPass?: (env: Env, scope: TenantScope, pass: string, target: GitDoorTarget) => Promise<Extract<GitWriter, {
+        kind: "actor";
+    }> | null>;
+    /** Admit a host-minted build job clone pass; omit when this host builds no Apps. */
+    buildGitPass?: (env: Env, scope: TenantScope, pass: string, target: GitDoorTarget) => Promise<Extract<GitWriter, {
+        kind: "actor";
+    }> | null>;
+    /** Further owner-only routes this host serves, after the owner guard. */
+    ownerRoutes?: (env: Env, scope: TenantScope) => Hono<OysterEnv>;
+}>;
+/** A tenant's whole Git host: the App server, `host.git` and the owner routes. */
+export type OysterGitWorkerHost = OysterHost & Readonly<{
+    git: OysterGitHost;
+}>;
+/**
+ * `host.keys.live`'s own shape: the live facts behind a key id, re-checked
+ * against the tenant's current owner on every read; null for an unknown,
+ * revoked, expired, suspended key, or one a since-reassigned tenant's
+ * former owner held. The one path every caller -- the HTTP/MCP host, a
+ * workspace's own Computer admission -- reaches a key's liveness through.
+ */
+export type OysterKeysLivePort = (keyId: string) => Promise<LiveOysterKey | null>;
+/** The one composition root of a Git Worker; build it once from its options. */
+export type OysterGitRoot<Env extends OysterGitWorkerEnv> = Readonly<{
+    /** Select a request's tenant once; `hostFor` reuses that admission for the same request. */
+    admit(env: Env, request: Request): Promise<ResolvedTenant | null>;
+    /** One pinned tenant's host. HTTP, MCP, Agents, Workflows and background wakes all reach it here. */
+    hostFor(env: Env, scope: TenantScope): OysterGitWorkerHost;
+}>;
+/** Compose a Git Worker's root from its one options value. */
+export declare function oysterGitRoot<Env extends OysterGitWorkerEnv>(options: OysterGitWorkerOptions<Env>): OysterGitRoot<Env>;
+/** The single-owner root's tenancy: the owner key or a named key, at the configured origin only. */
+export declare function ownerOrKeyTenancy(env: OysterGitWorkerEnv): OysterTenancy;
+/** The standalone Worker's `fetch` handler with the git door and owner routes. */
+export declare function createOysterGitWorker<Env extends OysterGitWorkerEnv>(root: OysterGitRoot<Env>): ExportedHandler<Env>;
+/** What `oysterWorkerGit` needs beyond the Worker's bindings. */
+export type OysterWorkerGitOptions<Env extends OysterGitWorkerEnv> = Pick<OysterGitWorkerOptions<Env>, "workflowGitPass" | "buildGitPass"> & Readonly<{
+    /** The tenant whose registry and repositories Git reaches. */
+    scope: TenantScope;
+}>;
+/** One live guest frame's Git custody; never a guest argument. */
+export type OysterGitFrame = Readonly<{
+    /** Verified backend custody of the host's live frame; its abort stops provider work. */
+    invocation: InvocationFrame<OysterInvocationHost>;
+    /** Host-owned physical adapter for this frame; admission stays packet-local. */
+    store?: ArtifactsGit;
+}>;
+/**
+ * `host.git` for an Oyster Worker: the git door's writer projection and the
+ * admitted, installation-scoped Artifacts path with the App's push policy and
+ * the Instance journal. Set it on your own `createOyster` host; the full
+ * standalone composition (`oysterGitWorkerHost`) uses this same builder.
+ */
+export declare function oysterWorkerGit<Env extends OysterGitWorkerEnv>(env: Env, options: OysterWorkerGitOptions<Env>, frame?: OysterGitFrame): OysterGitHost;
+/**
+ * One selected tenant's whole host from a root's options. Roots reach it through
+ * `oysterGitRoot(options).hostFor`; a cold directory passes its own resolved tenant.
+ */
+export declare function oysterGitWorkerHost<Env extends OysterGitWorkerEnv>(env: Env, options: OysterGitWorkerOptions<Env>, selected: ResolvedTenant): OysterGitWorkerHost;
+/** Deploy the MCP owner from the same root as createOysterGitWorker. */
+export declare function createOysterGitMcpOwner<Env extends OysterGitWorkerEnv>(root: OysterGitRoot<Env>): new (ctx: DurableObjectState, env: Env) => import("./mcp-owner.js").OysterMcpOwner<Env>;