@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/git.js

@@ -0,0 +1,64 @@
+/**
+ * Git and events for Apps: the GIT and EVENTS bindings a host grants an App
+ * backend, the git door that lets people and agents push to an App's
+ * repositories with ordinary git, and Standard Webhooks signing for events the
+ * host delivers. Credentials, remotes and webhook secrets stay in the host;
+ * the App sees repository names, git objects and its own events.
+ */
+import { readPacketLines, pktLine } from "@fungi.computer/agar/git-wire";
+import * as Schema from "effect/Schema";
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/** The protocol-v2 ls-refs request body. */
+export function lsRefsRequest() {
+    return encoder.encode(`${pktLine("command=ls-refs\n")}0001${pktLine("ref-prefix refs/\n")}0000`);
+}
+/** Parse an ls-refs response into refs. */
+export function parseLsRefs(response) {
+    const refs = [];
+    for (const raw of readPacketLines(response, true)) {
+        const [hash = "", name = ""] = decoder
+            .decode(raw)
+            .replace(/\n$/u, "")
+            .split(" ");
+        if (/^[0-9a-f]{40}$/u.test(hash) && name.startsWith("refs/"))
+            refs.push({ name, hash });
+    }
+    return refs;
+}
+async function hmac(key, message) {
+    const imported = await crypto.subtle.importKey("raw", new Uint8Array(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", imported, encoder.encode(message)));
+}
+/** A `whsec_` secret is base64 key bytes; any other secret is its own UTF-8. */
+function secretBytes(secret) {
+    if (!secret.startsWith("whsec_"))
+        return encoder.encode(secret);
+    return Uint8Array.from(atob(secret.slice(6)), (char) => char.charCodeAt(0));
+}
+function hex(bytes) {
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** The Standard Webhooks `webhook-signature` value for one delivery. */
+export async function signStandardWebhook(secret, id, timestamp, body) {
+    const signature = await hmac(secretBytes(secret), `${id}.${String(timestamp)}.${body}`);
+    return `v1,${btoa(String.fromCharCode(...signature))}`;
+}
+/** Headers for one signed delivery: Standard Webhooks plus `X-Hub-Signature-256`. */
+export async function webhookHeaders(secret, id, type, timestamp, body) {
+    return {
+        "content-type": "application/json",
+        "user-agent": "Oyster-Webhooks/1",
+        "webhook-id": id,
+        "webhook-timestamp": String(timestamp),
+        "webhook-signature": await signStandardWebhook(secret, id, timestamp, body),
+        // The headers receivers built for git hosts check.
+        "x-hub-signature-256": `sha256=${hex(await hmac(encoder.encode(secret), body))}`,
+        "x-github-delivery": id,
+        "x-github-event": type,
+    };
+}
+export { createGitDoor, gitDoorRoute, smartHttpExchange } from "./git-door.js";
+export { workflowGitPassPrefix } from "./git-auth.js";
+export { createAdmittedGit, createInstallationGitAdmission, } from "./git-admission.js";
+export { createGitPushJournal } from "./git-journal.js";

package/dist/guest-policy.d.ts

@@ -0,0 +1,9 @@
+/** Per-invocation budgets enforced by the guest Worker Loader, including facets. */
+export type GuestLimits = Readonly<{
+    /** Maximum guest CPU time in milliseconds. Defaults to 1,000. */
+    cpuMs: number;
+    /** Maximum guest subrequests. Defaults to 50; zero forbids subrequests. */
+    subRequests: number;
+}>;
+/** Validate host configuration and fill each omitted budget with its safe default. */
+export declare function guestLimits(input?: Partial<GuestLimits>): GuestLimits;

package/dist/guest-policy.js

@@ -0,0 +1,13 @@
+import * as Schema from "effect/Schema";
+const boundedInteger = Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isLessThanOrEqualTo(2147483647)));
+const limitsSchema = Schema.Struct({
+    cpuMs: boundedInteger.pipe(Schema.check(Schema.isGreaterThan(0))),
+    subRequests: boundedInteger.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+});
+/** Validate host configuration and fill each omitted budget with its safe default. */
+export function guestLimits(input = {}) {
+    return Object.freeze(Schema.decodeUnknownSync(limitsSchema)({
+        cpuMs: input.cpuMs ?? 1000,
+        subRequests: input.subRequests ?? 50,
+    }));
+}

package/dist/host.d.ts

@@ -0,0 +1,244 @@
+import type { KnapsackComputer } from "@fungi.computer/knapsack";
+import type { TenantPrincipal } from "./tenant.js";
+import { type GillCall, type GillReply } from "@fungi.computer/gills";
+import { type AppStorageWire } from "@fungi.computer/agar/storage";
+import type { OysterRootDirectory } from "./root-data.js";
+import { type AppGitPushFact, type GitPushQuestion, type GitPushVerdict, type GitWriter } from "@fungi.computer/agar/git";
+import { type GuestLimits } from "./guest-policy.js";
+import { type InvocationFacts } from "./invocation.js";
+export type { GuestLimits } from "./guest-policy.js";
+import { Hono } from "hono";
+import * as Schema from "effect/Schema";
+import { type BackgroundSyncRefusal } from "@fungi.computer/puffball/background-replay";
+import { type Installation, type InstallationReader } from "./apps/installation.js";
+import type { AppToolPolicy } from "./apps/tools.js";
+import type { LiveOysterKey } from "./keys.js";
+import { type AppMethodReply } from "@fungi.computer/agar/backend";
+import type { AppCapabilityId, HostActor } from "@fungi.computer/puffball/app";
+import { type CapabilityDescriptor } from "./capability-descriptor.js";
+export { capabilityDescriptorSchema, capabilityMethodKindSchema, capabilityMethodSchema, type CapabilityDescriptor, type CapabilityMethodKind, } from "./capability-descriptor.js";
+import type { Release } from "@fungi.computer/puffball";
+import { type Instance, type InstanceId, type OwnerState, type AppInstanceErrorCode } from "./index.js";
+import { type ArtifactStore } from "./release.js";
+import { type GitDoorTarget } from "./git.js";
+import type { AdmittedGit } from "./git-admission.js";
+import { type AppApi } from "@fungi.computer/puffball";
+export { ReleaseError, defaultAssetPolicy, parseRelease, resolveBackend, sha256, verifyRelease, type ArtifactStore, type VerifiedRelease, } from "./release.js";
+/**
+ * The anonymous reader of a public installation. The host admits it only when
+ * authentication refuses; it reaches that App's page and its `read` methods.
+ */
+export type OysterVisitor = Readonly<{
+    actor: Readonly<{
+        kind: "visitor";
+    }>;
+}>;
+/** Who an admitted request acts for: an authenticated tenant principal or the visitor. */
+export type OysterPrincipal = TenantPrincipal | OysterVisitor;
+/** Narrow an admitted principal to the anonymous public reader. */
+export declare function oysterPrincipalIsVisitor(principal: OysterPrincipal): principal is OysterVisitor;
+/** True only for a member admitted with the owner role. */
+export declare function oysterPrincipalIsOwner(principal: OysterPrincipal): principal is Readonly<{
+    actor: Extract<HostActor, {
+        kind: "member";
+    }>;
+    role: "owner";
+}>;
+/** Stable actor identity for host storage and backend attribution. */
+export declare function oysterPrincipalId(principal: TenantPrincipal): string;
+/** The outcome of authenticating one request. */
+export type OysterAuthResult = Readonly<{
+    kind: "admitted";
+    principal: TenantPrincipal;
+}> | Readonly<{
+    kind: "refused";
+    status: 401 | 403 | 404 | 429;
+    retryAfter?: number;
+}>;
+/** The host's sign-in: who may use this Oyster. */
+export type OysterAuth = Readonly<{
+    /** Resolve a retained actor through current host membership, without replaying credentials. */
+    resolve: (actor: HostActor) => Promise<TenantPrincipal | null>;
+    /** Authenticate one request from its headers or cookies. */
+    authenticate: (request: Request) => Promise<OysterAuthResult>;
+    /** Handle the browser sign-in form post; returns the response to send. */
+    login?: (request: Request) => Promise<Response>;
+}>;
+/** A serializable registry commit result, including across native DO RPC. */
+export type InstallationCommit = Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    code: "stale_authority";
+}>;
+/** Durable commits remain with the host's registry; reads are tenant-scoped. */
+export type InstallationStore = InstallationReader & Readonly<{
+    /** Commit one reducer-produced installation record. */
+    put: (installation: Installation) => Promise<void>;
+    /** Atomically commit only the authority version the owner reviewed. */
+    compareAndPut: (installation: Installation, expectedAuthorityVersion: number) => Promise<InstallationCommit>;
+}>;
+/** A JSON value crossing the method boundary. */
+export type OysterJson = Schema.Json;
+/** The result of one Instance operation; refusals carry Oyster's error code. */
+export type InstanceResult<T> = Readonly<{
+    ok: true;
+    value: T;
+}> | Readonly<{
+    ok: false;
+    code: AppInstanceErrorCode | "failed";
+    /** Closed host diagnostic; absent when the execution owner did not supply one. */
+    causeClass?: "Error" | "TypeError" | "RangeError" | "SyntaxError" | "AbortError" | "TimeoutError" | "Other";
+}>;
+/** One running App Instance, wherever the host runs it. */
+export type InstanceHandle = Readonly<{
+    /** Apply a complete owner state for `release`. */
+    apply: (state: OwnerState, release: Release) => Promise<InstanceResult<Instance>>;
+    /** Deliver an admitted Git push under this exact Instance selection. */
+    onGitPush: (facts: InvocationFacts, fact: AppGitPushFact) => Promise<void>;
+    /** Deliver a lane refusal only through an active zero-grant lifecycle frame. */
+    syncRefused: (facts: InvocationFacts, refusal: BackgroundSyncRefusal) => Promise<void>;
+    /** Ask a whole-push policy under host-admitted immutable caller facts. */
+    authorizeGitPush: (facts: InvocationFacts, question: GitPushQuestion) => Promise<GitPushVerdict>;
+    /** Forward an admitted HTTP request to the backend. */
+    fetch: (facts: InvocationFacts, request: Request) => Promise<Response>;
+    /** Invoke a declared read Gill through the same immutable invocation frame. */
+    gill: (facts: InvocationFacts, api: AppApi, source: string, input: GillCall) => Promise<InstanceResult<GillReply>>;
+    /** Invoke one declared App method; an App refusal is a refused reply. */
+    call: (facts: InvocationFacts, api: AppApi, name: string, input: OysterJson) => Promise<InstanceResult<AppMethodReply>>;
+}>;
+/** Finds the running Instance for an Instance ID. */
+export type InstanceDirectory = Readonly<{
+    /** The Instance with this ID. The adapter must enforce the supplied guest budgets. */
+    get: (instanceId: InstanceId, limits?: GuestLimits) => InstanceHandle;
+}>;
+/** An MCP endpoint mounted at `/mcp`. */
+export type OysterMcp = Readonly<{
+    /** Answer one MCP HTTP request. */
+    handleRequest: (request: Request) => Promise<Response>;
+    /** Close an explicitly supplied process-local adapter; remote owners expose no close. */
+    close?: () => Promise<void>;
+}>;
+/** What Oyster's git door needs from the host beyond sign-in and Instances. */
+export type OysterGitHost = Readonly<{
+    /** Project the authenticated host principal into the canonical writer grammar. */
+    writerOf(principal: TenantPrincipal): Extract<GitWriter, {
+        kind: "actor";
+    }>;
+    /** Admit a host-minted Workflow Git pass for exactly one repository and
+     * scope, as its arming member under the Workflow's branch grant. */
+    workflowPass?(pass: string, target: GitDoorTarget): Promise<Extract<GitWriter, {
+        kind: "actor";
+    }> | null>;
+    /** Admit a host-minted build job clone pass: one repository, read only, as
+     * the owner who started the build. */
+    buildPass?(pass: string, target: GitDoorTarget): Promise<Extract<GitWriter, {
+        kind: "actor";
+    }> | null>;
+    /** Construct the installation-scoped admitted store, policy and durable journal. */
+    git(installation: Installation): Promise<AdmittedGit>;
+}>;
+/** The host's admission of one capability request: who, for which installation. */
+export type CapabilityAdmission = Readonly<{
+    /** The principal the host authenticated for this request. */
+    principal: TenantPrincipal;
+    /** The enabled installation the gate admitted for this capability. */
+    installation: Installation;
+}>;
+/** Capability routes read the host's admission from `c.env`; they never authenticate. */
+export type CapabilityEnv = {
+    Bindings: CapabilityAdmission;
+};
+/** A capability adapter whose routes require live installation admission. */
+export type OysterCapability = Readonly<CapabilityDescriptor & {
+    /** The permission declared by an App Release to use this contract. */
+    permission: AppCapabilityId;
+    /** Routes relative to the descriptor's base path. */
+    routes: Hono<CapabilityEnv>;
+}>;
+/** What the host stamps once per request; inner routes read it with `c.get`. */
+export type OysterVariables = {
+    principal: OysterPrincipal;
+    installation?: Installation;
+};
+/** Owner routes run after the host's owner guard and read `c.get("principal")`. */
+export type OysterEnv = {
+    Variables: OysterVariables;
+};
+/** Everything a host supplies to run Oyster. */
+export type OysterHost = Readonly<{
+    auth: OysterAuth;
+    /** Host-held sealing key for member writes; never exposed to the guest.
+     * Absence refuses eligible named member writes, even when the App has no sync continuation.
+     */
+    backgroundOriginKey?: () => Promise<CryptoKey>;
+    artifacts: ArtifactStore;
+    installations: InstallationStore;
+    instances: InstanceDirectory;
+    /** Fixed Computer selected by the host; request input never selects it. */
+    computerId?: string;
+    /** The fixed Computer's advertised calls for one admitted caller, or null
+     * when the caller holds no Computer access (for a key, without its own
+     * `computer.use` grant). The Computer owner accepts each call against the
+     * authority the host issued.
+     */
+    computer?: (principal: OysterPrincipal) => KnapsackComputer | null | Promise<KnapsackComputer | null>;
+    /** Host-attested Agent tool policy; absence grants no App tool access. A
+     * key's App access is its own grants (Ear Tag), read through `keys.live`
+     * and `keyAppAccess`, never this port. */
+    appToolPolicy?: (actor: Extract<HostActor, {
+        kind: "agent";
+    }>) => AppToolPolicy | null | Promise<AppToolPolicy | null>;
+    /** The Ear Tag-backed key store this host owns. */
+    keys?: Readonly<{
+        /** One key's live facts by id; `null` for an unknown, revoked, expired or suspended key. */
+        live(keyId: string): Promise<LiveOysterKey | null>;
+    }>;
+    /** Guest CPU/subrequest budgets; defaults to 1,000 ms and 50 per invocation. */
+    guestLimits?: Partial<GuestLimits>;
+    /** Shared Mycelium MCP handler; it authenticates every request itself. */
+    mcp?: OysterMcp;
+    /** The git door for Apps that use GIT; mounted at `/git/*`. */
+    git?: OysterGitHost;
+    /** Owner-only `/api/*` routes the host adds (keys, webhooks); they read the
+     * admitted owner with `c.get("principal")` and never authenticate again. */
+    ownerRoutes?: Hono<OysterEnv>;
+    /** Adapters granted only when the Release declares them and admission passes. */
+    capabilities?: readonly OysterCapability[];
+    /**
+     * Root-owned desktop data and per-App storage; HTTP access remains
+     * owner-only. With it, the home installation's page is the trusted shell:
+     * `pageScript` must render that shell in the top-level `#oyster-shell`
+     * document, where it runs with this host's escalated permissions.
+     */
+    workbench?: Readonly<{
+        /** Read the owner's live installation directory. */
+        directory(): Promise<OysterRootDirectory>;
+        /** Open storage after fresh installation and owner admission. */
+        storage(installationId: string, ownerId: string): Pick<AppStorageWire, "read" | "write" | "reset"> & Readonly<{
+            /** Stream changes for an admitted declared storage key. */
+            events(key: string): Promise<Response>;
+        }>;
+    }>;
+    /** Root-selected home installation; the core never imports a specific home App. */
+    homeInstallationId?: string;
+    /** Browser composition supplied by a deployable host; defaults to Oyster shell. */
+    pageScript?: string;
+    /** Page title shown in the shell. */
+    title?: string;
+}>;
+/**
+ * Install a Release at `installationId`, or switch an already-live one onto
+ * it: the one path the POST install and PUT release-select routes share,
+ * and that a build owner's own install call reaches too. Nothing there (or
+ * only a deleted installation) is a fresh install; a live installation is
+ * switched in place, refusing a change of the installation's App identity.
+ */
+export declare function installOrSelect(host: OysterHost, installationId: string, release: Release, principal: OysterPrincipal): Promise<Response>;
+/**
+ * Create the Oyster App server: a Hono app that installs App Releases, serves
+ * their UI, forwards their backend requests and methods to their Instances,
+ * and mounts the host's MCP endpoint. The host's adapters decide where state
+ * lives and who may sign in.
+ */
+export declare function createOyster(host: OysterHost): Hono<OysterEnv>;