@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/r2-files.d.ts

@@ -0,0 +1,3 @@
+import type { FileSource } from "./files.js";
+/** Files in an R2 bucket under `prefix` (one workspace per prefix). */
+export declare function r2FileSource(bucket: R2Bucket, prefix: string): FileSource;

package/dist/r2-files.js

@@ -0,0 +1,79 @@
+/** Files in an R2 bucket under `prefix` (one workspace per prefix). */
+export function r2FileSource(bucket, prefix) {
+    const key = (path) => `${prefix}${path.slice(1)}`;
+    const dirKey = (path) => (path === "/" ? prefix : `${key(path)}/`);
+    return {
+        async list(path, limit, offset) {
+            const base = dirKey(path);
+            const entries = [];
+            let cursor;
+            do {
+                const options = { prefix: base, delimiter: "/" };
+                if (cursor !== undefined)
+                    options.cursor = cursor;
+                const page = await bucket.list(options);
+                for (const folder of page.delimitedPrefixes)
+                    entries.push({
+                        name: folder.slice(base.length, -1),
+                        type: "directory",
+                        size: 0,
+                        modifiedAt: 0,
+                    });
+                for (const object of page.objects) {
+                    const name = object.key.slice(base.length);
+                    // A directory marker is the directory itself, not an entry.
+                    if (name === "")
+                        continue;
+                    entries.push({
+                        name,
+                        type: "file",
+                        size: object.size,
+                        modifiedAt: object.uploaded.getTime(),
+                    });
+                }
+                cursor = page.truncated ? page.cursor : undefined;
+            } while (cursor !== undefined && entries.length < offset + limit + 1);
+            // An empty, unmarked directory other than the root does not exist.
+            if (entries.length === 0 &&
+                path !== "/" &&
+                (await bucket.head(dirKey(path))) === null)
+                return null;
+            entries.sort((a, b) => a.type === b.type
+                ? a.name.localeCompare(b.name)
+                : a.type === "directory"
+                    ? -1
+                    : 1);
+            const page = entries.slice(offset, offset + limit);
+            return {
+                path,
+                entries: page,
+                nextOffset: offset + limit < entries.length ? offset + limit : null,
+            };
+        },
+        async read(path) {
+            const object = await bucket.get(key(path));
+            return object === null
+                ? null
+                : new Uint8Array(await object.arrayBuffer());
+        },
+        async write(path, content) {
+            await bucket.put(key(path), content);
+        },
+        async mkdir(path) {
+            await bucket.put(dirKey(path), new Uint8Array());
+        },
+        async replace(path, expectedContent, content) {
+            const current = await bucket.get(key(path));
+            if (current === null || (await current.text()) !== expectedContent)
+                return { kind: "conflict" };
+            const bytes = new TextEncoder().encode(content);
+            // Compare-and-swap: R2 refuses the write if the object changed since the read.
+            const written = await bucket.put(key(path), bytes, {
+                onlyIf: { etagMatches: current.etag },
+            });
+            return written === null
+                ? { kind: "conflict" }
+                : { kind: "replaced", path, bytes: bytes.length };
+        },
+    };
+}

package/dist/release.d.ts

@@ -0,0 +1,83 @@
+import { type AppApi, type AppBuild, type AppDeclaration } from "@fungi.computer/puffball/app";
+import { type AssetBuild, type AssetBuildPolicy } from "@fungi.computer/puffball/assets";
+import { type DurableBackend } from "@fungi.computer/puffball/backend";
+import type { ArtifactRef, Release, Sha256Digest } from "@fungi.computer/puffball";
+/** Immutable Release bytes addressed by their artifact reference. */
+export type ArtifactStore = Readonly<{
+    /** Read the stored bytes for `artifactRef`, or `null` when absent. */
+    get: (artifactRef: ArtifactRef) => Promise<Uint8Array | null>;
+    /** Store bytes under `artifactRef`; the caller has verified the digest. */
+    put: (artifactRef: ArtifactRef, bytes: Uint8Array) => Promise<void>;
+}>;
+/** What a store knows of one object without reading it. */
+export type ArtifactHead = Readonly<{
+    byteLength: number;
+    /** The digest the store verified when it took the bytes, if it did. */
+    digest: Sha256Digest | null;
+}>;
+/** A store that can describe an object without reading its bytes. */
+export type ArtifactHeads = Readonly<{
+    /** Describe the object at `artifactRef`, or `null` when absent. */
+    head: (artifactRef: ArtifactRef) => Promise<ArtifactHead | null>;
+}>;
+/** Why a Release could not be read; the host maps it to an HTTP refusal. */
+export declare class ReleaseError extends Error {
+    readonly code: "artifact_missing" | "digest_mismatch" | "invalid_release" | "asset_missing";
+    readonly name = "ReleaseError";
+    constructor(code: "artifact_missing" | "digest_mismatch" | "invalid_release" | "asset_missing", message: string, options?: ErrorOptions);
+}
+/** Default bounds for an App's UI asset build. */
+export declare const defaultAssetPolicy: AssetBuildPolicy;
+/** A Release whose root, UI and backend artifacts were read and verified. */
+export type VerifiedRelease = Readonly<{
+    release: Release;
+    build: AppBuild;
+    /** The App API declared by the Release, or `null` when it has none. */
+    api: AppApi | null;
+    declaration: AppDeclaration | null;
+    ui: Readonly<{
+        kind: "html";
+        artifactRef: ArtifactRef;
+        digest: Sha256Digest;
+    }> | Readonly<{
+        kind: "assets";
+        build: AssetBuild;
+    }> | null;
+    backend: Readonly<{
+        artifactRef: ArtifactRef;
+        digest: Sha256Digest;
+    }> | null;
+}>;
+/** Hex SHA-256 digest in Puffball's `sha256:<hex>` form. */
+export declare function sha256(bytes: Uint8Array): Promise<string>;
+/** Read one artifact and refuse it unless its bytes match `digest`. */
+export declare function readVerified(store: ArtifactStore, artifactRef: ArtifactRef, digest: Sha256Digest): Promise<Uint8Array>;
+/** Decode an untrusted Release record, as an install request carries it. */
+export declare function parseRelease(value: unknown): Release;
+/**
+ * Read a Release root and verify every artifact it names: the UI document or
+ * asset build (and each asset object), and the backend descriptor.
+ */
+export declare function verifyRelease(store: ArtifactStore, release: Release, policy?: AssetBuildPolicy, 
+/**
+ * Read and check every UI asset now. Serving can skip this: each asset is
+ * verified against its digest when it is read.
+ */
+readAssets?: boolean): Promise<VerifiedRelease>;
+/**
+ * Resolve a Release to its verified durable backend without reading its UI:
+ * the root artifact, then the backend descriptor it names.
+ */
+export declare function resolveBackend(store: ArtifactStore, release: Release): Promise<Readonly<{
+    digest: Sha256Digest;
+    backend: DurableBackend;
+    declaration: AppDeclaration | null;
+}> | null>;
+/** A verified backend, as {@link resolveBackend} returns it. */
+export type ResolvedBackend = NonNullable<Awaited<ReturnType<typeof resolveBackend>>>;
+/**
+ * Verify each Release's backend once per owner. A Release's artifacts are
+ * immutable and content-addressed, so a verified read is reused for the same
+ * Release ID and artifact digest; a failed read is not cached.
+ */
+export declare function backendCache(store: ArtifactStore): (release: Release) => Promise<ResolvedBackend | null>;

package/dist/release.js

@@ -0,0 +1,167 @@
+import * as Schema from "effect/Schema";
+import { appBuildJsonSchema, } from "@fungi.computer/puffball/app";
+import { assetBuildMediaType, decodeAssetBuild, } from "@fungi.computer/puffball/assets";
+import { backendJsonSchema, } from "@fungi.computer/puffball/backend";
+import { releaseSchema } from "@fungi.computer/puffball/effect";
+/** Why a Release could not be read; the host maps it to an HTTP refusal. */
+export class ReleaseError extends Error {
+    code;
+    name = "ReleaseError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/** Default bounds for an App's UI asset build. */
+export const defaultAssetPolicy = {
+    maxManifestBytes: 1024 * 1024,
+    maxObjects: 2_000,
+    maxObjectBytes: 25 * 1024 * 1024,
+    maxTotalBytes: 100 * 1024 * 1024,
+};
+/** Hex SHA-256 digest in Puffball's `sha256:<hex>` form. */
+export async function sha256(bytes) {
+    const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", new Uint8Array(bytes)));
+    let hex = "";
+    for (const byte of hash)
+        hex += byte.toString(16).padStart(2, "0");
+    return `sha256:${hex}`;
+}
+/** Read one artifact and refuse it unless its bytes match `digest`. */
+export async function readVerified(store, artifactRef, digest) {
+    const bytes = await store.get(artifactRef);
+    if (bytes === null)
+        throw new ReleaseError("artifact_missing", `Missing ${artifactRef}`);
+    if ((await sha256(bytes)) !== digest)
+        throw new ReleaseError("digest_mismatch", `Digest mismatch ${artifactRef}`);
+    return bytes;
+}
+const decodeText = (bytes) => new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes);
+/** Decode an untrusted Release record, as an install request carries it. */
+export function parseRelease(value) {
+    try {
+        return Schema.decodeUnknownSync(releaseSchema)(value, {
+            onExcessProperty: "error",
+        });
+    }
+    catch (cause) {
+        throw new ReleaseError("invalid_release", "Invalid Release", { cause });
+    }
+}
+/**
+ * Read a Release root and verify every artifact it names: the UI document or
+ * asset build (and each asset object), and the backend descriptor.
+ */
+export async function verifyRelease(store, release, policy = defaultAssetPolicy, 
+/**
+ * Read and check every UI asset now. Serving can skip this: each asset is
+ * verified against its digest when it is read.
+ */
+readAssets = true) {
+    const rootBytes = await readVerified(store, release.artifact.artifactRef, release.artifact.artifactDigest);
+    let build;
+    try {
+        build = Schema.decodeUnknownSync(appBuildJsonSchema)(decodeText(rootBytes), {
+            onExcessProperty: "error",
+        });
+    }
+    catch (cause) {
+        throw new ReleaseError("invalid_release", "Invalid App root", { cause });
+    }
+    let ui = null;
+    if ("ui" in build) {
+        const bytes = await readVerified(store, build.ui.artifactRef, build.ui.digest);
+        if (build.ui.mediaType === assetBuildMediaType) {
+            let assets;
+            try {
+                assets = decodeAssetBuild(bytes, policy);
+            }
+            catch (cause) {
+                throw new ReleaseError("invalid_release", "Invalid assets", { cause });
+            }
+            // One asset at a time: a Release's assets together can exceed an
+            // isolate's memory, each alone is bounded by its policy.
+            if (readAssets)
+                for (const asset of assets.assets)
+                    await readVerified(store, asset.artifactRef, asset.digest);
+            ui = { kind: "assets", build: assets };
+        }
+        else
+            ui = {
+                kind: "html",
+                artifactRef: build.ui.artifactRef,
+                digest: build.ui.digest,
+            };
+    }
+    let backend = null;
+    if ("backend" in build) {
+        await readBackend(store, build.backend.artifactRef, build.backend.digest);
+        backend = {
+            artifactRef: build.backend.artifactRef,
+            digest: build.backend.digest,
+        };
+    }
+    return {
+        release,
+        build,
+        api: build.declaration?.api ?? null,
+        declaration: build.declaration ?? null,
+        ui,
+        backend,
+    };
+}
+/** Read and decode a verified durable backend descriptor. */
+async function readBackend(store, artifactRef, digest) {
+    const bytes = await readVerified(store, artifactRef, digest);
+    try {
+        return Schema.decodeUnknownSync(backendJsonSchema)(decodeText(bytes), {
+            onExcessProperty: "error",
+        });
+    }
+    catch (cause) {
+        throw new ReleaseError("invalid_release", "Invalid backend", { cause });
+    }
+}
+/**
+ * Resolve a Release to its verified durable backend without reading its UI:
+ * the root artifact, then the backend descriptor it names.
+ */
+export async function resolveBackend(store, release) {
+    const rootBytes = await readVerified(store, release.artifact.artifactRef, release.artifact.artifactDigest);
+    let build;
+    try {
+        build = Schema.decodeUnknownSync(appBuildJsonSchema)(decodeText(rootBytes), {
+            onExcessProperty: "error",
+        });
+    }
+    catch (cause) {
+        throw new ReleaseError("invalid_release", "Invalid App root", { cause });
+    }
+    if (!("backend" in build))
+        return null;
+    return {
+        digest: build.backend.digest,
+        declaration: build.declaration ?? null,
+        backend: await readBackend(store, build.backend.artifactRef, build.backend.digest),
+    };
+}
+/**
+ * Verify each Release's backend once per owner. A Release's artifacts are
+ * immutable and content-addressed, so a verified read is reused for the same
+ * Release ID and artifact digest; a failed read is not cached.
+ */
+export function backendCache(store) {
+    const verified = new Map();
+    return (release) => {
+        const key = `${release.releaseId}:${release.artifact.artifactDigest}`;
+        let entry = verified.get(key);
+        if (entry === undefined) {
+            entry = resolveBackend(store, release).catch((cause) => {
+                verified.delete(key);
+                throw cause;
+            });
+            verified.set(key, entry);
+        }
+        return entry;
+    };
+}

package/dist/root-data.d.ts

@@ -0,0 +1,86 @@
+import type { Release } from "@fungi.computer/puffball";
+import { createAppStorage } from "./app-storage.js";
+import type { InstallationStore, verifyRelease } from "./host.js";
+import { type AppDirectoryEntry } from "./shell/app-directory.js";
+import type { WorkbenchPlatformDestination } from "./shell/workbench-model.js";
+/** Role choices belong to the root owner, independently of Release declarations. */
+export type OysterRootRoles = Readonly<Record<string, Readonly<{
+    surfaceId: string | null;
+    chosen: boolean;
+}>>>;
+/** Shared workbench metadata, without a hosted Team's administration or grants. */
+export type OysterRootDirectory = Readonly<{
+    apps: readonly AppDirectoryEntry[];
+    roles: OysterRootRoles;
+    /** Fixed host-selected Computer context; metadata conveys no operation rights. */
+    computer?: Readonly<{
+        computerId: string;
+        name: string;
+    }>;
+}>;
+/** Existing installation, Release and SQLite owners supplied by the root. */
+export type OysterRootDataOptions = Parameters<typeof createAppStorage>[0] & Readonly<{
+    installations: Pick<InstallationStore, "list">;
+    /** Reuse the root's verified Release resolver; metadata grants no access. */
+    resolveRelease(release: Release): Promise<Pick<Awaited<ReturnType<typeof verifyRelease>>, "declaration" | "ui">>;
+}>;
+/** Data adapters for a standalone workbench over the root's existing owners. */
+export declare function createOysterRootData(options: OysterRootDataOptions): {
+    /** Each open(authorize) receives fresh host admission and Release-declared keys. */
+    storage: {
+        purgeInstallation: (address: string) => void;
+        purgeMember: (memberId: string, throughVersion: number) => void;
+        openInstallation(authorize: () => import("effect/Effect").Effect<import("./app-storage.js").AppStorageInstallationAdmission, Error>): {
+            read: (key: string) => import("effect/Effect").Effect<{
+                readonly value: import("effect/Schema").Json;
+                readonly source: "team" | "member" | "none";
+                readonly team: {
+                    readonly value: import("effect/Schema").Json;
+                    readonly revision: number;
+                } | null;
+                readonly member: {
+                    readonly value: import("effect/Schema").Json;
+                    readonly revision: number;
+                } | null;
+                readonly canWriteTeam: boolean;
+            }, import("@fungi.computer/agar").AppStorageError, never>;
+            write: (input: import("@fungi.computer/agar").AppStorageWrite) => import("effect/Effect").Effect<{
+                revision: number;
+            }, import("@fungi.computer/agar").AppStorageError, never>;
+            reset: (input: import("@fungi.computer/agar").AppStorageReset) => import("effect/Effect").Effect<{
+                revision: number;
+            }, import("@fungi.computer/agar").AppStorageError, never>;
+        };
+        open(authorize: () => import("effect/Effect").Effect<import("./app-storage.js").AppStorageAdmission, Error>): {
+            read: (key: string) => import("effect/Effect").Effect<{
+                readonly value: import("effect/Schema").Json;
+                readonly source: "team" | "member" | "none";
+                readonly team: {
+                    readonly value: import("effect/Schema").Json;
+                    readonly revision: number;
+                } | null;
+                readonly member: {
+                    readonly value: import("effect/Schema").Json;
+                    readonly revision: number;
+                } | null;
+                readonly canWriteTeam: boolean;
+            }, import("@fungi.computer/agar").AppStorageError, never>;
+            write: (input: import("@fungi.computer/agar").AppStorageWrite) => import("effect/Effect").Effect<{
+                revision: number;
+            }, import("@fungi.computer/agar").AppStorageError, never>;
+            reset: (input: import("@fungi.computer/agar").AppStorageReset) => import("effect/Effect").Effect<{
+                revision: number;
+            }, import("@fungi.computer/agar").AppStorageError, never>;
+            events: (key: string) => import("effect/Stream").Stream<{
+                readonly appId: string;
+                readonly key: string;
+                readonly scope: "team" | "member";
+                readonly revision: number;
+            } | null, import("@fungi.computer/agar").AppStorageError, never>;
+        };
+    };
+    /** Project the current installations without minting permissions or role choices. */
+    directory(): Promise<OysterRootDirectory>;
+    /** No standalone platform navigation destination is implemented yet. */
+    platformDestinations(): readonly WorkbenchPlatformDestination[];
+};

package/dist/root-data.js

@@ -0,0 +1,69 @@
+import { resolveAppRoles, } from "@fungi.computer/puffball/app";
+import { createAppStorage } from "./app-storage.js";
+import { addressKey, appDirectoryEntrySchema, } from "./shell/app-directory.js";
+/** Data adapters for a standalone workbench over the root's existing owners. */
+export function createOysterRootData(options) {
+    const storage = createAppStorage(options);
+    return {
+        /** Each open(authorize) receives fresh host admission and Release-declared keys. */
+        storage,
+        /** Project the current installations without minting permissions or role choices. */
+        async directory() {
+            const installations = await options.installations.list();
+            const projected = await Promise.all(installations
+                .filter((installation) => installation.status !== "deleted")
+                .map(async (installation) => {
+                const resolved = await options.resolveRelease(installation.release);
+                const declaration = resolved.declaration;
+                const address = {
+                    kind: "installation",
+                    installationId: installation.installationId,
+                };
+                const surfaceId = addressKey(address);
+                const surfacePath = `/apps/${encodeURIComponent(installation.installationId)}/`;
+                const available = installation.status === "enabled" && resolved.ui !== null;
+                const availability = available ? "available" : "unavailable";
+                const entry = {
+                    address,
+                    installationId: installation.installationId,
+                    surfaceId,
+                    appId: installation.release.appId,
+                    displayName: declaration?.displayName,
+                    icon: declaration?.icon ?? null,
+                    releaseId: installation.release.releaseId,
+                    authorityVersion: installation.authorityVersion,
+                    enforcement: null,
+                    handlers: [...(declaration?.handlers ?? [])],
+                    roles: [...(declaration?.roles ?? [])],
+                    declaredCapabilities: [...(declaration?.capabilities ?? [])],
+                    commands: [...(declaration?.commands ?? [])],
+                    gills: [...(declaration?.gills ?? [])],
+                    availability,
+                    surface: available ? { stableRoute: surfacePath } : null,
+                    surfacePath,
+                };
+                if (declaration?.calls !== undefined)
+                    entry.calls = declaration.calls;
+                // Built from the declaration's own typed roles, not the
+                // directory entry's widened (string[]) projection of them.
+                const candidate = {
+                    surfaceId,
+                    availability,
+                    roles: declaration?.roles ?? [],
+                };
+                return { entry: appDirectoryEntrySchema.parse(entry), candidate };
+            }));
+            // Standalone has no PUT route and no stored choice: per the ADR, the
+            // effective holder of an unchosen role is the first available listed
+            // App declaring it.
+            return {
+                apps: projected.map((app) => app.entry),
+                roles: resolveAppRoles(new Map(), projected.map((app) => app.candidate)),
+            };
+        },
+        /** No standalone platform navigation destination is implemented yet. */
+        platformDestinations() {
+            return [];
+        },
+    };
+}