@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/internal/delivery.d.ts

@@ -0,0 +1,12 @@
+import { type AppGitPushFact } from "@fungi.computer/agar/git";
+import { type BackgroundWake } from "@fungi.computer/puffball/background-replay";
+import type { OysterHost } from "../host.js";
+/** Re-admit a retained push and deliver it directly to the current Instance.
+ * Durable host delivery uses the same fresh checks as initial push admission;
+ * this path never calls the producer's optional enqueue callback. */
+export declare function deliverGitPush(host: Pick<OysterHost, "artifacts" | "installations" | "instances" | "guestLimits">, installationId: string, fact: AppGitPushFact): Promise<void>;
+/** Re-admit a stored member through the same directory and method gate as a click. */
+export declare function deliverBackground(host: OysterHost, raw: BackgroundWake): Promise<Readonly<{
+    status: "accepted" | "refused";
+    more: boolean;
+}>>;

package/dist/internal/delivery.js

@@ -0,0 +1,167 @@
+import { appGitPushFactSchema, } from "@fungi.computer/agar/git";
+import { backgroundWakeSchema, readmitBackground, } from "@fungi.computer/puffball/background-replay";
+import { z } from "zod";
+import { admits } from "../apps/gate.js";
+import { backgroundWakeKey } from "../git-journal.js";
+import { guestLimits } from "../guest-policy.js";
+import { selectionOf } from "../index.js";
+import { APP_INVOCATION_CEILING_MS, invocationAuthorityOf, invocationCallerContext, invocationFacts, } from "../invocation.js";
+import { defaultAssetPolicy, verifyRelease, } from "../release.js";
+import { admittedBackgroundOrigins } from "./background-origins.js";
+import { hostGateFacts, releaseCache } from "./host-gate.js";
+async function admitGitPush(host, readRelease, installationId, raw) {
+    const fact = appGitPushFactSchema.parse(raw);
+    const installation = await host.installations.get(installationId);
+    if (installation?.status !== "enabled")
+        throw new Error("Git push installation unavailable");
+    const release = await readRelease(installation.release);
+    const { declaration } = release;
+    if (!declaration?.receives?.includes("git.push") ||
+        !declaration.capabilities.includes("git.repository"))
+        return null;
+    const current = await host.installations.get(installationId);
+    if (current?.status !== "enabled" ||
+        current.instanceId !== installation.instanceId ||
+        current.authorityVersion !== installation.authorityVersion ||
+        current.release.releaseId !== installation.release.releaseId)
+        throw new Error("Git push installation changed");
+    return { installation: current, release, fact };
+}
+function deliverAdmittedGitPush(host, installation, release, fact) {
+    return host.instances
+        .get(selectionOf(installation).instanceId, guestLimits(host.guestLimits))
+        .onGitPush({
+        ...invocationAuthorityOf(installation, release),
+        subject: {
+            kind: "lifecycle",
+            name: "onGitPush",
+            eventId: fact.eventId,
+        },
+        deadlineAt: Date.now() + APP_INVOCATION_CEILING_MS,
+    }, fact);
+}
+/** Re-admit a retained push and deliver it directly to the current Instance.
+ * Durable host delivery uses the same fresh checks as initial push admission;
+ * this path never calls the producer's optional enqueue callback. */
+export async function deliverGitPush(host, installationId, fact) {
+    const admitted = await admitGitPush(host, (release) => verifyRelease(host.artifacts, release, defaultAssetPolicy, false), installationId, fact);
+    if (admitted !== null)
+        await deliverAdmittedGitPush(host, admitted.installation, admitted.release, admitted.fact);
+}
+/** Re-admit a stored member through the same directory and method gate as a click. */
+export async function deliverBackground(host, raw) {
+    const wake = backgroundWakeSchema.parse(raw);
+    const available = async () => {
+        const current = await host.installations.get(wake.installationId);
+        return current?.status === "enabled" && current.instanceId !== null
+            ? current
+            : null;
+    };
+    if ((await available()) === null)
+        return { status: "refused", more: false };
+    const readRelease = releaseCache(host.artifacts);
+    let admitted;
+    const decision = await readmitBackground(wake, {
+        resolve: (actor) => host.auth.resolve(actor),
+        admit: async (principal) => {
+            const installation = await available();
+            if (installation === null)
+                return { kind: "refused", code: "unavailable" };
+            const release = await readRelease(installation.release);
+            const method = release.declaration?.backend?.sync?.method;
+            if (method === undefined ||
+                release.api?.methods[method]?.effect !== "write")
+                return { kind: "refused", code: "denied" };
+            const gate = await hostGateFacts(host, installation, release, principal);
+            const verdict = admits(gate, {
+                kind: "method",
+                name: method,
+                input: {},
+                via: "ui",
+            });
+            if (verdict.kind === "refused") {
+                switch (verdict.code) {
+                    case "unavailable":
+                    case "stale_authority":
+                    case "not_approved":
+                    case "level_too_low":
+                    case "requires_not_granted":
+                        return { kind: "refused", code: verdict.code };
+                    case "not_declared":
+                    case "approval_required":
+                    case "invalid_input":
+                    case "visitor_read_only":
+                        return { kind: "refused", code: "denied" };
+                }
+            }
+            const origins = admittedBackgroundOrigins(gate);
+            admitted = {
+                installation,
+                release,
+                method,
+                grants: verdict.grants,
+                origins,
+            };
+            return {
+                kind: "admitted",
+                context: invocationCallerContext(principal, host.computerId ?? null),
+            };
+        },
+    });
+    if (decision.kind === "retry")
+        throw new Error("Background admission changed; retry");
+    if (decision.kind === "refused") {
+        const current = await available();
+        if (current === null || decision.code === "installation_unavailable")
+            return { status: "refused", more: false };
+        const release = await readRelease(current.release);
+        const authority = invocationAuthorityOf(current, release);
+        const refusal = { lane: wake.lane, code: decision.code };
+        await host.instances
+            .get(authority.instanceId, guestLimits(host.guestLimits))
+            .syncRefused({
+            ...authority,
+            grants: [],
+            subject: { kind: "lifecycle", name: "syncRefused", ...refusal },
+            deadlineAt: Date.now() + APP_INVOCATION_CEILING_MS,
+        }, refusal);
+        return { status: "accepted", more: false };
+    }
+    if (!admitted?.release.api)
+        throw new Error("Background continuation was not admitted");
+    const deadlineAt = Date.now() + APP_INVOCATION_CEILING_MS;
+    const facts = invocationFacts.fromCaller({
+        ...invocationAuthorityOf(admitted.installation, admitted.release),
+        grants: admitted.grants,
+    }, {
+        ...decision.context,
+        idempotencyKey: backgroundWakeKey(wake),
+    }, { deadlineAt, grantExpiresAt: deadlineAt }, { name: admitted.method, effect: "write" });
+    if (facts.subject.kind !== "call")
+        throw new Error("Background replay must be a call");
+    const result = await host.instances
+        .get(facts.instanceId, guestLimits(host.guestLimits))
+        .call({
+        ...facts,
+        grants: [
+            ...facts.grants,
+            { binding: "BACKGROUND", operations: ["admit"] },
+        ],
+        subject: {
+            ...facts.subject,
+            replay: {
+                lane: wake.lane,
+                epoch: wake.epoch,
+                admitted: admitted.origins,
+            },
+        },
+    }, admitted.release.api, admitted.method, {});
+    if (!result.ok)
+        throw new Error(`Background continuation failed: ${result.code}`);
+    if (result.value.kind === "refused")
+        throw new Error(`Background continuation refused: ${result.value.code}`);
+    return {
+        status: "accepted",
+        more: z.object({ more: z.boolean() }).parse(result.value.value).more,
+    };
+}

package/dist/internal/host-gate.d.ts

@@ -0,0 +1,14 @@
+/** Release verification and gate facts shared by the HTTP host and its delivery engines. */
+import type { Release } from "@fungi.computer/puffball";
+import type { GateFacts } from "../apps/gate.js";
+import type { Installation } from "../apps/installation.js";
+import type { OysterHost, OysterPrincipal } from "../host.js";
+import { type ArtifactStore, type VerifiedRelease } from "../release.js";
+/**
+ * Verify each Release once per process: a failed read is not cached, so the
+ * next request reads it again. Installation verified every asset; serving
+ * verifies each on read.
+ */
+export declare function releaseCache(artifacts: ArtifactStore): (release: Release) => Promise<VerifiedRelease>;
+/** The gate facts one principal presents to one installation. */
+export declare function hostGateFacts(host: OysterHost, installation: Installation, release: VerifiedRelease, principal: OysterPrincipal): Promise<GateFacts>;

package/dist/internal/host-gate.js

@@ -0,0 +1,62 @@
+import { emptyAppDeclaration } from "@fungi.computer/puffball/app";
+import { deriveDeclaredOperations } from "../apps/operations.js";
+import { keyAppAccess } from "../keys.js";
+import { defaultAssetPolicy, verifyRelease, } from "../release.js";
+/**
+ * Verify each Release once per process: a failed read is not cached, so the
+ * next request reads it again. Installation verified every asset; serving
+ * verifies each on read.
+ */
+export function releaseCache(artifacts) {
+    const verified = new Map();
+    return (release) => {
+        const key = `${release.releaseId}:${release.artifact.artifactDigest}`;
+        let entry = verified.get(key);
+        if (entry === undefined) {
+            // A failed read is not cached: the next request reads the Release again.
+            // Installation verified every asset; serving verifies each on read.
+            entry = verifyRelease(artifacts, release, defaultAssetPolicy, false).then((value) => value, (cause) => {
+                verified.delete(key);
+                throw cause;
+            });
+            verified.set(key, entry);
+        }
+        return entry;
+    };
+}
+/**
+ * Only Agents and keys hold tool policy; members and visitors never ask. An
+ * Agent keeps its one blanket policy; a key's access is its own grants for
+ * this one installation -- `null` when its live key is unknown, revoked,
+ * expired or suspended, or simply does not reach this installation, which
+ * then refuses `not_approved`, the same as an Agent with no approval.
+ */
+async function hostToolPolicy(host, actor, installationId) {
+    if (actor.kind === "agent")
+        return (await host.appToolPolicy?.(actor)) ?? null;
+    if (actor.kind !== "team-key")
+        return null;
+    const key = (await host.keys?.live(actor.keyId)) ?? null;
+    return key === null ? null : keyAppAccess(key, installationId);
+}
+/** The gate facts one principal presents to one installation. */
+export async function hostGateFacts(host, installation, release, principal) {
+    const { actor } = principal;
+    const declaration = release.declaration ?? emptyAppDeclaration;
+    const toolPolicy = await hostToolPolicy(host, actor, installation.installationId);
+    return {
+        installation,
+        declaration,
+        declaredOperations: await deriveDeclaredOperations(installation.release, declaration, host.capabilities ?? []),
+        api: release.api,
+        principal: { actor, role: "role" in principal ? principal.role : null },
+        access: toolPolicy === null
+            ? null
+            : {
+                level: toolPolicy.level,
+                bindingName: installation.installationId,
+                revision: toolPolicy.revision,
+                grantedBy: toolPolicy.grantedBy,
+            },
+    };
+}

package/dist/internal/registry-installations.d.ts

@@ -0,0 +1,6 @@
+/** The standalone registry Durable Object as an `InstallationStore`. */
+import type { InstallationStore } from "../host.js";
+import type { TenantScope } from "../tenant.js";
+import type { OysterWorkerEnv } from "../workers.js";
+/** Read and commit installations in the scope's registry. */
+export declare function registryInstallations(env: Pick<OysterWorkerEnv, "REGISTRY">, scope: TenantScope): InstallationStore;

package/dist/internal/registry-installations.js

@@ -0,0 +1,12 @@
+/** Read and commit installations in the scope's registry. */
+export function registryInstallations(env, scope) {
+    const registry = () => env.REGISTRY.getByName(scope.durableName("registry"));
+    return {
+        list: async () => registry().list(),
+        get: async (id) => registry().get(id),
+        put: async (installation) => {
+            await registry().put(installation, scope.tenantId);
+        },
+        compareAndPut: async (installation, expectedAuthorityVersion) => await registry().compareAndPut(installation, expectedAuthorityVersion, scope.tenantId),
+    };
+}

package/dist/invocation.d.ts

@@ -0,0 +1,251 @@
+import type { OysterHost, OysterPrincipal } from "./host.js";
+import type { VerifiedRelease } from "./release.js";
+import type { Installation } from "./apps/installation.js";
+import { type InvocationGrants } from "./apps/gate.js";
+import * as Schema from "effect/Schema";
+import { type AppBackendBindingName, type AppMethodCallContext, type WorkflowAttestation } from "@fungi.computer/puffball/app";
+import { type BackgroundOrigin, type ClaimedJobAdmission } from "@fungi.computer/puffball/background-replay";
+import { type InstanceId } from "./index.js";
+/** One App invocation may hold authority for at most the Hub grant's lifetime. */
+export declare const APP_INVOCATION_CEILING_MS = 60000;
+/** Host-admitted facts; shape decoding does not establish host authority. */
+export declare const invocationFactsSchema: Schema.Struct<{
+    readonly instanceId: Schema.Codec<InstanceId, string, never, never>;
+    readonly selection: Schema.Struct<{
+        readonly instanceId: Schema.Codec<InstanceId, string, never, never>;
+        readonly owner: Schema.Struct<{
+            readonly kind: Schema.Literals<readonly ["installation", "deployment"]>;
+            readonly id: Schema.NonEmptyString;
+        }>;
+        readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+        readonly releaseId: Schema.refine<import("@fungi.computer/puffball").ReleaseId, Schema.String>;
+        readonly authorityVersion: Schema.Number;
+    }>;
+    readonly artifactDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
+    readonly subject: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"call">;
+        readonly context: Schema.declareConstructor<{
+            computerId: string | null;
+            actor: {
+                kind: "member";
+                memberId: string;
+            } | {
+                kind: "agent";
+                agentId: string;
+            } | {
+                kind: "team-key";
+                keyId: string;
+            };
+            backgroundLane?: string | undefined;
+            backgroundOrigin?: {
+                method: string;
+                seal: string;
+            } | undefined;
+            role?: "member" | "owner" | undefined;
+            soleMember?: true | undefined;
+            workflow?: {
+                workflowId: string;
+                runId: string;
+                nodeId: string;
+                armedBy: {
+                    kind: "member";
+                    memberId: string;
+                } | {
+                    kind: "agent";
+                    agentId: string;
+                } | {
+                    kind: "team-key";
+                    keyId: string;
+                };
+            } | undefined;
+            idempotencyKey?: string | undefined;
+        }, {
+            computerId: string | null;
+            actor: {
+                kind: "member";
+                memberId: string;
+            } | {
+                kind: "agent";
+                agentId: string;
+            } | {
+                kind: "team-key";
+                keyId: string;
+            };
+            backgroundLane?: string | undefined;
+            backgroundOrigin?: {
+                method: string;
+                seal: string;
+            } | undefined;
+            role?: "member" | "owner" | undefined;
+            soleMember?: true | undefined;
+            workflow?: {
+                workflowId: string;
+                runId: string;
+                nodeId: string;
+                armedBy: {
+                    kind: "member";
+                    memberId: string;
+                } | {
+                    kind: "agent";
+                    agentId: string;
+                } | {
+                    kind: "team-key";
+                    keyId: string;
+                };
+            } | undefined;
+            idempotencyKey?: string | undefined;
+        }, readonly [], {
+            computerId: string | null;
+            actor: {
+                kind: "member";
+                memberId: string;
+            } | {
+                kind: "agent";
+                agentId: string;
+            } | {
+                kind: "team-key";
+                keyId: string;
+            };
+            backgroundLane?: string | undefined;
+            backgroundOrigin?: {
+                method: string;
+                seal: string;
+            } | undefined;
+            role?: "member" | "owner" | undefined;
+            soleMember?: true | undefined;
+            workflow?: {
+                workflowId: string;
+                runId: string;
+                nodeId: string;
+                armedBy: {
+                    kind: "member";
+                    memberId: string;
+                } | {
+                    kind: "agent";
+                    agentId: string;
+                } | {
+                    kind: "team-key";
+                    keyId: string;
+                };
+            } | undefined;
+            idempotencyKey?: string | undefined;
+        }>;
+        /** Originating Session supplied by capability acquisition, never App arguments. */
+        readonly sessionId: Schema.optionalKey<Schema.String>;
+        /** Captured Agent approval, supplied by the host after current policy admission. */
+        readonly agentPolicy: Schema.optionalKey<Schema.Struct<{
+            readonly policyRevision: Schema.NonEmptyString;
+            readonly grantorMemberId: Schema.NonEmptyString;
+        }>>;
+        /** Verified method metadata; raw fetch frames have no declared method. */
+        readonly method: Schema.optionalKey<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly effect: Schema.Literals<readonly ["read", "write", "external"]>;
+        }>>;
+        /** Host-marked, freshly admitted replay; never read from guest input. */
+        readonly replay: Schema.optionalKey<Schema.Struct<{
+            readonly lane: Schema.NonEmptyString;
+            readonly epoch: Schema.Number;
+            readonly admitted: Schema.$Array<Schema.String>;
+        }>>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"lifecycle">;
+        readonly name: Schema.Literal<"onGitPush">;
+        readonly eventId: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"lifecycle">;
+        readonly name: Schema.Literal<"syncRefused">;
+        readonly lane: Schema.String;
+        readonly code: Schema.Literals<("access_changed" | "installation_unavailable")[]>;
+    }>]>;
+    readonly grants: Schema.$Array<Schema.Struct<{
+        readonly binding: Schema.refine<"BACKGROUND" | "GIT" | "EVENTS" | "APPS" | "WORKFLOWS" | "APP_STORAGE" | "MEDIA" | "COMPUTER" | "INBOX" | "AGENTS", Schema.String>;
+        readonly operations: Schema.$Array<Schema.NonEmptyString>;
+    }>>;
+    readonly deadlineAt: Schema.Number;
+    readonly ancestry: Schema.$Array<Schema.Codec<InstanceId, string, never, never>>;
+}>;
+/** The immutable authority and attribution supplied at host admission. */
+export type InvocationFacts = typeof invocationFactsSchema.Type;
+/** Method name/effect taken from a verified API; raw backend requests have no method. */
+export type InvocationMethod = NonNullable<Extract<InvocationFacts["subject"], {
+    kind: "call";
+}>["method"]>;
+/** Captured policy identity; the Agent id remains on the canonical call actor. */
+export type InvocationAgentPolicy = NonNullable<Extract<InvocationFacts["subject"], {
+    kind: "call";
+}>["agentPolicy"]>;
+/** A live frame stays inside its Instance; host state and signals never cross RPC. */
+export type InvocationFrame<Host = unknown> = Readonly<{
+    frameId: string;
+    facts: InvocationFacts;
+    host: Host;
+    signal: AbortSignal;
+}>;
+/** One mutable origin latch on the host state of one invocation, never shared across frames. */
+export type BackgroundFrameState = {
+    /** This frame's one claimed-origin decision; never carried into another frame. */
+    origin: "unchecked" | "admitted" | "refused";
+};
+/** Block replay capability effects before job-origin admission; storage permits claiming/settling. */
+export declare function assertBackgroundBinding(frame: InvocationFrame<BackgroundFrameState>, binding: AppBackendBindingName): void;
+/** Consume this frame's one origin check before awaiting verification, then retain only its decision. */
+export declare function admitBackgroundFrame(key: CryptoKey, frame: InvocationFrame<BackgroundFrameState>, raw: unknown): Promise<ClaimedJobAdmission>;
+/** The host's native guest-abort and authority-close hooks. */
+export type InvocationGatePorts<Host> = Readonly<{
+    /** Stop the guest when the captured invocation's authority closes. */
+    abortGuest: () => Promise<void>;
+    /** Release the host resources belonging to this completed or revoked frame. */
+    close: (frame: InvocationFrame<Host>) => Promise<void>;
+    /** Host clock used to enforce the frame deadline; defaults to Date.now. */
+    now?: () => number;
+}>;
+/** One invocation owner shared by Hub shards and standalone Instances. */
+export type InvocationGate<Host> = Readonly<{
+    /** Run work within one immutable frame and close its authority afterward. */
+    run: <A>(facts: InvocationFacts, host: Host, work: (frame: InvocationFrame<Host>) => Promise<A>) => Promise<A>;
+    /** Resolve the sole admitted frame, refusing outside an active invocation. */
+    active: () => InvocationFrame<Host>;
+    /** Close live authority, optionally restricted to frames of a selected run. */
+    revoke: (reason?: Error, target?: Readonly<{
+        runId: string;
+    }>) => Promise<void>;
+    /** Serialize supervisor metadata/erasure without opening guest authority. */
+    exclusive: <A>(work: () => Promise<A>) => Promise<A>;
+}>;
+/** Decode only identities minted from the invocation-frame ID family. */
+export declare const invocationFrameIdSchema: Schema.String;
+/** Serialize authority, preempt replay only for verified writes, and close each guest before admission. */
+export declare function createInvocationGate<Host>(ports: InvocationGatePorts<Host>): InvocationGate<Host>;
+/** Verified selection, artifact and binding grants before caller attribution. */
+export type InvocationAuthority = Omit<InvocationFacts, "subject" | "deadlineAt">;
+/** The host supplies both deadlines; the frame cannot outlive either. */
+export type InvocationDeadline = Readonly<{
+    deadlineAt: number;
+    grantExpiresAt: number;
+}>;
+/**
+ * Project an admitted principal into App attribution; only the host chooses
+ * the fixed Computer context. The App caller grammar has no visitor actor, so
+ * the anonymous public reader is attributed as the reserved `visitor` key
+ * without a Computer. Host admission reads the principal, never this projection.
+ */
+export declare function invocationCallerContext(principal: OysterPrincipal, computerId: string | null): AppMethodCallContext;
+/** Shared host-held caller/Workflow fact builders, never guest argument decoders. */
+export declare const invocationFacts: {
+    /** Combine host-admitted caller facts with the invocation and grant deadlines. */
+    fromCaller: (authority: InvocationAuthority, context: AppMethodCallContext, deadline: InvocationDeadline, method?: InvocationMethod, sessionId?: string, agentPolicy?: InvocationAgentPolicy) => InvocationFacts;
+    /** Attribute an already host-admitted published node to its retained arming actor. */
+    fromWorkflowNode: (authority: InvocationAuthority, input: Readonly<{
+        workflow: WorkflowAttestation;
+        computerId: string | null;
+        role?: AppMethodCallContext["role"];
+        idempotencyKey: string;
+    }>, deadline: InvocationDeadline) => InvocationFacts;
+};
+/** Authority comes from the admitted installation and its verified backend bytes. */
+export declare function invocationAuthorityOf(installation: Installation, release: VerifiedRelease, ancestry?: readonly InstanceId[]): InvocationAuthority;
+/** Mint standalone facts only after host caller and Release admission. */
+export declare function admittedCallerFacts(installation: Installation, release: VerifiedRelease, context: AppMethodCallContext, grants: InvocationGrants, ancestry?: readonly InstanceId[], sessionId?: string, agentPolicy?: InvocationAgentPolicy, method?: InvocationMethod, origin?: BackgroundOrigin): InvocationFacts;
+/** Seal the host-verified named method after its current admission checks. */
+export declare function admittedMethodCallerFacts(host: Pick<OysterHost, "backgroundOriginKey">, installation: Installation, release: VerifiedRelease, context: AppMethodCallContext, grants: InvocationGrants, method: InvocationMethod, ancestry?: readonly InstanceId[], sessionId?: string, agentPolicy?: InvocationAgentPolicy): Promise<InvocationFacts>;