@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/apps/permissions.js

@@ -0,0 +1,255 @@
+import * as z from "zod";
+import { permissionCatalog } from "./catalog.js";
+import { sha256DigestSchema } from "@fungi.computer/puffball/effect";
+import { appAuthoritySchema, declaredOperationsSchema, ownerCodec, grantCommandSchema, } from "./installation.js";
+/** Includes newly declared operations and capabilities the owner has narrowed. */
+export function pendingCapabilities(authority, declaration, declaredOperations) {
+    return declaration.capabilities.filter((capability) => {
+        if (permissionCatalog[capability].consent === "affordance")
+            return false;
+        const grant = authority.approvedGrants.find((row) => row.capability === capability);
+        return (grant === undefined ||
+            (grant.resources !== "tenant-scope" && grant.resources.length === 0) ||
+            declaredOperations.capabilities
+                .find((row) => row.capability === capability)
+                ?.operations.some((operation) => !grant.operations.includes(operation)) === true);
+    });
+}
+/** Bound the real SDK request; an Allow never silently widens selected resources. */
+export function grantRequestFor(authority, facts, request, window) {
+    if (authority.declaredOperationsDigest !== facts.declaredOperations.digest)
+        return { kind: "refused", code: "stale_authority" };
+    const requested = [
+        ...new Set([...(request.agents ?? []), ...(request.computers ?? [])]),
+    ];
+    if (requested.some((capability) => !facts.declaration.capabilities.includes(capability)))
+        return { kind: "refused", code: "not_declared" };
+    const adds = [];
+    for (const capability of requested) {
+        const existing = authority.approvedGrants.find((row) => row.capability === capability);
+        const operations = facts.declaredOperations.capabilities.find((row) => row.capability === capability)?.operations ?? [];
+        if (existing !== undefined &&
+            existing.resources !== "tenant-scope" &&
+            existing.resources.length > 0) {
+            // approvedGrantSchema admits only capabilityApproved: true.
+            // A replay can use that approval, but cannot extend its finite scope.
+            if (permissionCatalog[capability].scope === "computer" &&
+                window.computerId !== null &&
+                existing.resources.some((resource) => resource.kind === "computer" && resource.id === window.computerId) &&
+                operations.every((operation) => existing.operations.includes(operation)))
+                continue;
+            return { kind: "customize" };
+        }
+        if (existing?.resources === "tenant-scope" &&
+            operations.every((operation) => existing.operations.includes(operation)))
+            continue;
+        let resources = "tenant-scope";
+        if (permissionCatalog[capability].scope === "computer") {
+            // Only the embedding host supplies this fact, never the App's request.
+            const computerId = window.computerId;
+            if (computerId == null)
+                return { kind: "refused", code: "window_scope_unavailable" };
+            resources = [{ kind: "computer", id: computerId }];
+        }
+        adds.push({ capability, grant: { operations, resources } });
+    }
+    if (adds.length === 0)
+        return { kind: "covered" };
+    return {
+        kind: "ask",
+        adds,
+        command: { kind: "change-grants", changes: adds },
+    };
+}
+/** The saved operation ceiling is the starting point, including empty operation rows. */
+export function draftOf(authority) {
+    return new Map(authority.approvedGrants.map(({ capability, operations, resources }) => [
+        capability,
+        { operations, resources },
+    ]));
+}
+function sameGrant(a, b) {
+    if (a == null || b == null)
+        return a == null && b == null;
+    const sameValues = (left, right) => left.length === right.length &&
+        left.every((value) => right.includes(value));
+    if (!sameValues(a.operations, b.operations))
+        return false;
+    if (a.resources === "tenant-scope" || b.resources === "tenant-scope")
+        return a.resources === b.resources;
+    return (a.resources.length === b.resources.length &&
+        a.resources.every((resource) => b.resources !== "tenant-scope" &&
+            b.resources.some((other) => resource.kind === other.kind && resource.id === other.id)));
+}
+/** An edit changes one capability; unrelated saved operations and scopes are retained. */
+export function editPermissions(draft, edit, declared) {
+    const row = declared.capabilities.find(({ capability }) => capability === edit.capability);
+    const policy = permissionCatalog[edit.capability];
+    if (row === undefined || policy.consent === "affordance")
+        return draft;
+    const next = new Map(draft);
+    const existing = draft.get(edit.capability);
+    const enabled = existing ?? {
+        operations: row.operations,
+        resources: "tenant-scope",
+    };
+    switch (edit.kind) {
+        case "switch":
+            next.set(edit.capability, edit.on ? enabled : null);
+            break;
+        case "all":
+            if (policy.scope === null)
+                return draft;
+            next.set(edit.capability, edit.on ? { ...enabled, resources: "tenant-scope" } : null);
+            break;
+        case "resource": {
+            if (policy.scope !== edit.resource.kind ||
+                existing?.resources === "tenant-scope")
+                return draft;
+            const resources = existing?.resources ?? [];
+            const kept = resources.filter((resource) => resource.kind !== edit.resource.kind ||
+                resource.id !== edit.resource.id);
+            const changed = edit.on ? [...kept, edit.resource] : kept;
+            next.set(edit.capability, changed.length === 0 ? null : { ...enabled, resources: changed });
+            break;
+        }
+        case "operation": {
+            if (edit.capability !== "apps.call" ||
+                !row.operations.includes(edit.operation))
+                return draft;
+            const kept = (existing?.operations ?? []).filter((operation) => operation !== edit.operation);
+            const operations = edit.on ? [...kept, edit.operation] : kept;
+            next.set(edit.capability, operations.length === 0 ? null : { ...enabled, operations });
+            break;
+        }
+    }
+    return next;
+}
+/** Only touched capability rows cross the save boundary. */
+export function planGrantChange(baseline, draft) {
+    const saved = draftOf(baseline);
+    const capabilities = new Set([...saved.keys(), ...draft.keys()]);
+    return [...capabilities].flatMap((capability) => sameGrant(saved.get(capability), draft.get(capability))
+        ? []
+        : [{ capability, grant: draft.get(capability) ?? null }]);
+}
+/** A conflict preserves the person's edits while taking fresh untouched capabilities. */
+export function rebaseDraft(draft, baseline, current) {
+    const rebased = new Map(draftOf(current));
+    for (const change of planGrantChange(baseline, draft))
+        rebased.set(change.capability, change.grant);
+    return rebased;
+}
+/** Serializable host facts; the browser derives presentation, never authority. */
+export const appPermissionsWireSchema = z.strictObject({
+    authority: appAuthoritySchema,
+    declaredOperations: declaredOperationsSchema,
+});
+/** Every declared permission is visible, including removable saved resources no longer listed by the host. */
+export function permissionScreen(input) {
+    const pending = pendingCapabilities(input.authority, {
+        capabilities: input.declaredOperations.capabilities.map((row) => row.capability),
+    }, input.declaredOperations);
+    const draft = draftOf(input.authority);
+    const grouped = new Map();
+    for (const { capability } of input.declaredOperations.capabilities) {
+        const group = permissionCatalog[capability].group;
+        grouped.set(group, [...(grouped.get(group) ?? []), capability]);
+    }
+    const column = (capability) => {
+        const { label, caption, description, sigil, warning } = permissionCatalog[capability];
+        return {
+            capability,
+            label,
+            caption,
+            description,
+            sigil,
+            warning,
+            pending: pending.includes(capability),
+        };
+    };
+    return {
+        canEdit: input.canEdit,
+        pending,
+        groups: [...grouped].map(([id, capabilities]) => {
+            const scoped = capabilities.filter((capability) => permissionCatalog[capability].scope !== null);
+            const scope = scoped.length === 0
+                ? null
+                : permissionCatalog[scoped[0] ?? "apps.open"].scope;
+            const resources = new Map(input.resources
+                .filter((resource) => resource.kind === scope)
+                .map((resource) => [resource.id, resource]));
+            for (const capability of scoped) {
+                const grant = draft.get(capability);
+                if (grant == null || grant.resources === "tenant-scope")
+                    continue;
+                for (const resource of grant.resources) {
+                    if (resource.kind === scope && !resources.has(resource.id))
+                        resources.set(resource.id, { ...resource, label: resource.id });
+                }
+            }
+            const row = (resource, label) => ({
+                resource,
+                label,
+                cells: scoped.map((capability) => {
+                    const grant = draft.get(capability);
+                    const state = grant == null
+                        ? "off"
+                        : grant.resources === "tenant-scope"
+                            ? resource === "all"
+                                ? "on"
+                                : "via-all"
+                            : resource !== "all" &&
+                                grant.resources.some((ref) => ref.kind === resource.kind && ref.id === resource.id)
+                                ? "on"
+                                : "off";
+                    return { capability, state };
+                }),
+            });
+            return {
+                id,
+                scope,
+                columns: scoped.map(column),
+                rows: scope === null
+                    ? []
+                    : [
+                        row("all", scope === "computer" ? "All Computers" : "All Agents"),
+                        ...[...resources.values()].map((resource) => row(resource, resource.label)),
+                    ],
+                switches: capabilities
+                    .filter((capability) => permissionCatalog[capability].scope === null)
+                    .map((capability) => ({
+                    ...column(capability),
+                    on: permissionCatalog[capability].consent === "affordance" ||
+                        draft.get(capability) != null,
+                })),
+                operations: capabilities.includes("apps.call")
+                    ? (input.declaredOperations.capabilities.find((capability) => capability.capability === "apps.call")?.operations ?? []).map((operation) => ({
+                        capability: "apps.call",
+                        operation,
+                        on: draft.get("apps.call")?.operations.includes(operation) === true,
+                    }))
+                    : [],
+            };
+        }),
+    };
+}
+/** Owner-direct permission page and JSON projection. Copy stays in the catalog. */
+export const permissionPinsSchema = z.strictObject({
+    storeGeneration: z.string().min(1),
+    authorityVersion: z.number().int().positive(),
+    artifactDigest: ownerCodec(sha256DigestSchema),
+});
+/** Permission edit command coupled to the version pins read by the owner. */
+export const permissionSaveSchema = permissionPinsSchema.extend({
+    command: grantCommandSchema,
+});
+/** Owner permission-page identity, artifact and current permission facts. */
+export const appPermissionPageSchema = z.strictObject({
+    storeGeneration: permissionPinsSchema.shape.storeGeneration,
+    installationId: z.string(),
+    appId: z.string(),
+    appName: z.string(),
+    artifactDigest: ownerCodec(sha256DigestSchema),
+    permissions: appPermissionsWireSchema,
+});

package/dist/boot-capability-route.d.ts

@@ -0,0 +1,15 @@
+import { type BootCapabilityStore } from "./boot-capability.js";
+/** The artifact bucket read the route needs; an R2 bucket is one. */
+export type BootAssetBucket = Readonly<{
+    get(key: string): Promise<Readonly<{
+        size: number;
+        body: ReadableStream<Uint8Array>;
+    }> | null>;
+}>;
+export type BootCapabilityRouteOptions = Readonly<{
+    configuredOrigin: string;
+    bucket: BootAssetBucket;
+    capabilities: BootCapabilityStore;
+}>;
+/** Worker-only HTTPS endpoint for a single digest-authorized boot lease. */
+export declare function serveBootCapability(request: Request, options: BootCapabilityRouteOptions): Promise<Response | null>;

package/dist/boot-capability-route.js

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import { parseReleaseId } from "@fungi.computer/puffball";
+import { z } from "zod";
+import { BOOT_CAPABILITY_HEADER, } from "./boot-capability.js";
+import {} from "./boot-gate.js";
+import { defaultAssetPolicy } from "./release.js";
+import { bootAssetUrl, bootHostScript, bootParentDocument, candidateAssetUrls, candidateSecurityHeaders, parentSecurityHeaders, } from "./boot-mount.js";
+const tokenSchema = z.string().regex(/^[A-Za-z0-9_-]{43}$/);
+const candidatePreflightPathSchema = z
+    .tuple([
+    z.literal("_boot"),
+    z.string(),
+    z.literal("candidate"),
+    z.string().min(1),
+])
+    .rest(z.string().min(1));
+const capabilityPreflightSchema = z.object({
+    method: z.literal("OPTIONS"),
+    search: z.literal(""),
+    origin: z.literal("null"),
+    requestedMethod: z.literal("GET"),
+    requestedHeaders: z
+        .string()
+        .trim()
+        .toLowerCase()
+        .pipe(z.literal(BOOT_CAPABILITY_HEADER)),
+    path: candidatePreflightPathSchema,
+});
+/** Worker-only HTTPS endpoint for a single digest-authorized boot lease. */
+export async function serveBootCapability(request, options) {
+    const url = new URL(request.url);
+    if (!url.pathname.startsWith("/_boot/"))
+        return null;
+    const configured = new URL(options.configuredOrigin);
+    // The same origins checkBootPage opens: https, or http on loopback only.
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(configured.hostname);
+    if ((configured.protocol !== "https:" &&
+        !(configured.protocol === "http:" && loopback)) ||
+        configured.pathname !== "/" ||
+        configured.search !== "" ||
+        configured.hash !== "" ||
+        configured.username !== "" ||
+        configured.password !== "" ||
+        url.origin !== configured.origin)
+        return refusal(404);
+    const segments = url.pathname.split("/");
+    if (isCapabilityPreflight(request, url, segments))
+        return capabilityPreflight();
+    const token = tokenSchema.safeParse(request.headers.get(BOOT_CAPABILITY_HEADER));
+    if (request.method !== "GET" ||
+        url.search !== "" ||
+        segments[2] === "" ||
+        !token.success ||
+        segments.length < 4 ||
+        segments[0] !== "" ||
+        segments[1] !== "_boot")
+        return refusal(404);
+    const tokenDigest = createHash("sha256")
+        .update(token.data, "utf8")
+        .digest("hex");
+    const lease = await options.capabilities.resolve(tokenDigest, Date.now());
+    if (lease === null)
+        return refusal(404);
+    // The capability store returns a lease already decoded at its persistence boundary.
+    const checkedLease = lease;
+    if (checkedLease.identity.releaseId !== segments[2])
+        return refusal(404);
+    const assets = checkedLease.assets.map(bootUiAsset);
+    const ui = {
+        identity: checkedLease.identity,
+        base: checkedLease.base,
+        assets,
+    };
+    const root = new URL(`/_boot/${checkedLease.identity.releaseId}/`, configured.origin);
+    const candidateBase = new URL("candidate/", root);
+    const urls = candidateAssetUrls(ui, candidateBase.href);
+    const entry = bootAssetUrl(candidateBase.href, checkedLease.base, "/index.html");
+    if (Date.now() >= checkedLease.expiresAt)
+        return refusal(404);
+    const parentPath = `${root.pathname}index.html`;
+    const bridgePath = `${root.pathname}bridge.js`;
+    if (url.pathname === parentPath) {
+        return new Response(bootParentDocument(checkedLease.identity, entry), {
+            status: 200,
+            headers: {
+                ...parentSecurityHeaders(candidateBase.href),
+                "content-type": "text/html; charset=utf-8",
+            },
+        });
+    }
+    if (url.pathname === bridgePath) {
+        return new Response(bootHostScript, {
+            status: 200,
+            headers: {
+                ...parentSecurityHeaders(candidateBase.href),
+                "content-type": "text/javascript; charset=utf-8",
+            },
+        });
+    }
+    const assetIndex = urls.findIndex((assetUrl) => {
+        const asset = new URL(assetUrl);
+        return asset.origin === url.origin && asset.pathname === url.pathname;
+    });
+    const asset = checkedLease.assets[assetIndex];
+    if (asset === undefined)
+        return refusal(404);
+    if (Date.now() >= checkedLease.expiresAt)
+        return refusal(404);
+    const object = await options.bucket.get(asset.artifactRef);
+    if (object?.size !== asset.byteLength)
+        return refusal(404);
+    const headers = new Headers({
+        ...candidateSecurityHeaders(candidateBase.href),
+        "content-type": asset.contentType,
+        "x-content-type-options": "nosniff",
+    });
+    if (request.headers.get("origin") === "null") {
+        headers.set("access-control-allow-origin", "null");
+        headers.set("vary", "Origin");
+    }
+    const hash = createHash("sha256");
+    let byteLength = 0;
+    const verified = object.body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            if (Date.now() >= checkedLease.expiresAt) {
+                controller.error(new Error("Boot asset lease expired"));
+                return;
+            }
+            byteLength += chunk.byteLength;
+            if (byteLength > defaultAssetPolicy.maxObjectBytes) {
+                controller.error(new Error("Boot asset exceeds its size limit"));
+                return;
+            }
+            hash.update(chunk);
+            controller.enqueue(chunk);
+        },
+        flush(controller) {
+            if (byteLength !== asset.byteLength ||
+                `sha256:${hash.digest("hex")}` !== asset.digest)
+                controller.error(new Error("Boot asset verification failed"));
+        },
+    }));
+    return new Response(verified, { status: 200, headers });
+}
+function isCapabilityPreflight(request, url, segments) {
+    const preflight = capabilityPreflightSchema.safeParse({
+        method: request.method,
+        search: url.search,
+        origin: request.headers.get("origin"),
+        requestedMethod: request.headers.get("access-control-request-method"),
+        requestedHeaders: request.headers.get("access-control-request-headers"),
+        path: segments.slice(1),
+    });
+    if (!preflight.success)
+        return false;
+    try {
+        parseReleaseId(preflight.data.path[1]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function capabilityPreflight() {
+    return new Response(null, {
+        status: 204,
+        headers: {
+            "access-control-allow-origin": "null",
+            "access-control-allow-methods": "GET",
+            "access-control-allow-headers": BOOT_CAPABILITY_HEADER,
+            "cache-control": "no-store",
+            "referrer-policy": "no-referrer",
+            vary: "Origin, Access-Control-Request-Method, Access-Control-Request-Headers",
+            "x-content-type-options": "nosniff",
+        },
+    });
+}
+function bootUiAsset(asset) {
+    return {
+        path: asset.path,
+        contentType: asset.contentType,
+        artifactRef: asset.artifactRef,
+        digest: asset.digest,
+    };
+}
+function refusal(status) {
+    return new Response("Boot resource unavailable", {
+        status,
+        headers: {
+            "cache-control": "no-store",
+            "content-type": "text/plain; charset=utf-8",
+            "referrer-policy": "no-referrer",
+            "x-content-type-options": "nosniff",
+        },
+    });
+}

package/dist/boot-capability.d.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { type BootUi, type UiBootCheckOutcome } from "./boot-gate.js";
+import type { BootPageResult, BootPageTarget } from "./browser/boot.js";
+export declare const BOOT_CAPABILITY_HEADER = "x-oyster-boot-capability";
+declare const bootCapabilityAssetSchema: z.ZodObject<{
+    path: z.ZodString;
+    contentType: z.ZodString;
+    artifactRef: z.ZodPipe<z.ZodString, z.ZodTransform<import("@fungi.computer/puffball").ArtifactRef, string>>;
+    digest: z.ZodPipe<z.ZodString, z.ZodTransform<import("@fungi.computer/puffball").Sha256Digest, string>>;
+    byteLength: z.ZodNumber;
+}, z.core.$strict>;
+export declare const bootCapabilityLeaseSchema: z.ZodObject<{
+    id: z.ZodString;
+    identity: z.ZodObject<{
+        appId: z.ZodString;
+        releaseId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@fungi.computer/puffball").ReleaseId, string>>;
+        surfaceId: z.ZodLiteral<"host-boot">;
+    }, z.core.$strict>;
+    base: z.ZodString;
+    expiresAt: z.ZodNumber;
+    assets: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        contentType: z.ZodString;
+        artifactRef: z.ZodPipe<z.ZodString, z.ZodTransform<import("@fungi.computer/puffball").ArtifactRef, string>>;
+        digest: z.ZodPipe<z.ZodString, z.ZodTransform<import("@fungi.computer/puffball").Sha256Digest, string>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const bootCapabilityGrantSchema: z.ZodObject<{
+    lease: z.ZodObject<{
+        id: z.ZodString;
+        identity: z.ZodObject<{
+            appId: z.ZodString;
+            releaseId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@fungi.computer/puffball").ReleaseId, string>>;
+            surfaceId: z.ZodLiteral<"host-boot">;
+        }, z.core.$strict>;
+        base: z.ZodString;
+        expiresAt: z.ZodNumber;
+        assets: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            contentType: z.ZodString;
+            artifactRef: z.ZodPipe<z.ZodString, z.ZodTransform<import("@fungi.computer/puffball").ArtifactRef, string>>;
+            digest: z.ZodPipe<z.ZodString, z.ZodTransform<import("@fungi.computer/puffball").Sha256Digest, string>>;
+            byteLength: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    tokenDigest: z.ZodString;
+}, z.core.$strict>;
+export type BootCapabilityAsset = z.output<typeof bootCapabilityAssetSchema>;
+export type BootCapabilityLease = z.output<typeof bootCapabilityLeaseSchema>;
+export type BootCapabilityGrant = z.output<typeof bootCapabilityGrantSchema>;
+/** Host-owned bounded Durable Object port. No raw token crosses this seam. */
+export type BootCapabilityStore = Readonly<{
+    issue(grant: BootCapabilityGrant): Promise<void>;
+    resolve(tokenDigest: string, now: number): Promise<BootCapabilityLease | null>;
+    revoke(id: string): Promise<void>;
+}>;
+/** Build metadata retained by the lease must exactly match the verified boot UI. */
+export declare function capabilityAssets(assets: BootUi["assets"], byteLengths: readonly number[]): BootCapabilityAsset[];
+export declare function validateCapabilityAssetSet(lease: BootCapabilityLease): void;
+/** The artifact bucket's metadata read; asset bytes are never read here. */
+export type BootCapabilityBucket = Readonly<{
+    head(key: string): Promise<Readonly<{
+        size: number;
+    }> | null>;
+}>;
+/**
+ * Mint one boot capability for every host: a fresh 256-bit token for the
+ * caller's request header, only its SHA-256 digest in the store, and a lease
+ * whose asset sizes come from the bucket's own metadata. An asset the bucket
+ * does not hold, or one beyond the asset policy, refuses before anything is
+ * stored.
+ */
+export declare function issueBootCapability(input: Readonly<{
+    ui: BootUi;
+    bucket: BootCapabilityBucket;
+    capabilities: BootCapabilityStore;
+    expiresAt: number;
+}>): Promise<Readonly<{
+    token: string;
+    leaseId: string;
+}>>;
+/** What one boot page report needs from its host. */
+export type BootPageReportInput = Readonly<{
+    /** The host's configured origin for its `/_boot/` route, or null when unset. */
+    origin: string | null;
+    /** `checkBootPage` over the host's browser, or null without one. */
+    check: ((target: BootPageTarget) => Promise<BootPageResult>) | null;
+    /** The Release's UI as artifact references, or null when it has no UI. */
+    readUi: () => Promise<BootUi | null>;
+    bucket: BootCapabilityBucket;
+    capabilities: BootCapabilityStore;
+    now: () => number;
+}>;
+/**
+ * One UI page check for a Release, for every host, reading no UI bytes:
+ * issue a capability, open the pinned boot page, revoke the capability, and
+ * report in the boot gate's vocabulary. A page that did not mount fails,
+ * with diagnostics sanitized by the gate's schema; a timeout, unconfirmed
+ * cleanup, an unavailable runner, or no browser or origin is not checked.
+ */
+export declare function reportBootPage(input: BootPageReportInput): Promise<UiBootCheckOutcome>;
+export {};