@fungi.computer/oyster 0.1.0 → 0.3.0

package/dist/apps/installation.js

@@ -4,7 +4,8 @@ import * as Result from "effect/Result";
 import { appCapabilityIdSchema, appApiMethodNameSchema, } from "@fungi.computer/puffball/app";
 import { hostActorSchema } from "@fungi.computer/puffball/app-method-runtime";
 import { appIdSchema, releaseSchema, sha256DigestSchema, } from "@fungi.computer/puffball/effect";
-import { instanceIdSchema } from "../index.js";
+import { instanceIdSchema } from "../instance-id.js";
+import { permissionCatalog } from "./catalog.js";
 /** Reuse the owning Effect codec at a JSON/storage boundary. */
 export function ownerCodec(schema) {
     const decode = Schema.decodeUnknownResult(schema, {
@@ -20,30 +21,28 @@ export function ownerCodec(schema) {
     });
 }
 /** Installation names cannot contain the tenant separator. */
-export const installationIdSchema = z
-    .string()
-    .regex(/^[a-z](?:[a-z0-9]|-(?!-)){0,62}$/u);
+export const installationIdSchema = z.lazy(() => z.string().regex(/^[a-z](?:[a-z0-9]|-(?!-)){0,62}$/u));
 /** A resource identity minted and resolved by the host, never by this module. */
-const resourceRefSchema = z
+export const resourceRefSchema = z.lazy(() => z
     .strictObject({
     kind: z.string().min(1),
     id: z.string().min(1),
 })
-    .readonly();
-const operationsSchema = z
+    .readonly());
+const operationsSchema = z.lazy(() => z
     .array(z.string().min(1))
     .refine((values) => new Set(values).size === values.length, "Operations must be unique")
-    .readonly();
+    .readonly());
 /**
  * Consent approves capabilities, with explicit operation and resource ceilings.
  * A Release adding a method that requires an already-approved capability needs
  * no new consent; a new capability does. Release selection intersects stored
  * operations instead of adding approvals. Each Worker call is still restricted
  * to that method's declared requires, never the App's complete capability set.
- * Only an approved install or set-grants command mints capabilityApproved.
+ * Only an approved install or change-grants command mints capabilityApproved.
  * Empty operation rows retain that consent; removing the capability revokes it.
  * route:app.methods rows record approval detail, not a method allowlist: narrowing
- * them in set-grants does not restrict methods using an approved capability.
+ * them in change-grants does not restrict methods using an approved capability.
  * Exact operation rows are enforced for capability routes and backend bindings.
  */
 export const approvedGrantSchema = z
@@ -58,31 +57,139 @@ export const approvedGrantSchema = z
 })
     .readonly();
 /** One grant per capability keeps operation/resource pairs unambiguous. */
-const approvedGrantsSchema = z
+const approvedGrantsSchema = z.lazy(() => z
     .array(approvedGrantSchema)
     .refine((grants) => new Set(grants.map((grant) => grant.capability)).size === grants.length, "Capabilities must be unique")
-    .readonly();
-/** Shorthand is accepted only on a command and expanded at approval time. */
-const grantRequestSchema = z.union([
-    z.literal("none"),
-    z.literal("declared"),
-    z
-        .array(approvedGrantSchema
+    .readonly());
+/** A bounded owner edit. Unnamed approvals are not part of the command. */
+export const grantChangeSchema = z
+    .strictObject({
+    capability: ownerCodec(appCapabilityIdSchema),
+    grant: approvedGrantSchema
         .unwrap()
-        .omit({ capabilityApproved: true })
-        .readonly())
-        .refine((grants) => new Set(grants.map((grant) => grant.capability)).size === grants.length, "Capabilities must be unique")
-        .readonly(),
-]);
-const versionSchema = z.number().int().positive();
+        .omit({ capabilityApproved: true, capability: true })
+        .readonly()
+        .nullable(),
+})
+    .readonly();
+const grantChangesSchema = z
+    .array(grantChangeSchema)
+    .min(1)
+    .refine((changes) => new Set(changes.map((change) => change.capability)).size ===
+    changes.length, "Capabilities must be unique")
+    .readonly();
+const versionSchema = z.lazy(() => z.number().int().positive());
 /** An owner's approval of a fixed operation snapshot. */
-const approvalSchema = z
+const approvalSchema = z.lazy(() => z
     .strictObject({
     by: hostActorSchema,
     at: z.number().int().nonnegative(),
     authorityVersion: versionSchema,
 })
-    .readonly();
+    .readonly());
+/** The complete grant state. Hosts own storage and compare-and-set commits. */
+export const appAuthoritySchema = z.strictObject({
+    authorityVersion: versionSchema,
+    declaredOperationsDigest: ownerCodec(sha256DigestSchema),
+    approvedGrants: approvedGrantsSchema,
+    approval: approvalSchema.nullable(),
+});
+export const grantCommandSchema = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("install") }),
+    z.strictObject({
+        kind: z.literal("change-grants"),
+        changes: grantChangesSchema,
+    }),
+    z.strictObject({ kind: z.literal("select-release") }),
+    z.strictObject({ kind: z.literal("delete") }),
+]);
+/** One host-independent approval policy; selection only intersects existing grants. */
+export function applyGrantCommand(current, rawCommand, context) {
+    const refuse = (code) => Result.fail({ kind: "refused", code });
+    const parsed = grantCommandSchema.safeParse(rawCommand);
+    if (!parsed.success)
+        return refuse("invalid_command");
+    const command = parsed.data;
+    if ((current === null && command.kind !== "install") ||
+        (current !== null && command.kind === "install"))
+        return refuse("invalid_command");
+    if ((context.expectedVersion ?? 0) !== (current?.authorityVersion ?? 0) ||
+        (current !== null &&
+            command.kind !== "select-release" &&
+            current.declaredOperationsDigest !== context.declaredOperations.digest))
+        return refuse("stale_authority");
+    if (context.principal.role === null ||
+        context.principal.actor.kind === "visitor" ||
+        (command.kind === "change-grants" && context.principal.role !== "owner"))
+        return refuse("not_owner");
+    const declared = (capability) => context.declaredOperations.capabilities.find((row) => row.capability === capability)?.operations ?? [];
+    const version = (current?.authorityVersion ?? 0) + 1;
+    let grants = current?.approvedGrants ?? [];
+    let approval = current?.approval ?? null;
+    switch (command.kind) {
+        case "install":
+            grants =
+                context.principal.role === "owner"
+                    ? context.declaration.capabilities
+                        .filter((capability) => permissionCatalog[capability].consent === "install")
+                        .map((capability) => ({
+                        capability,
+                        capabilityApproved: true,
+                        operations: declared(capability),
+                        resources: "tenant-scope",
+                    }))
+                    : [];
+            break;
+        case "change-grants": {
+            for (const { capability, grant } of command.changes) {
+                if (!context.declaration.capabilities.includes(capability) ||
+                    grant?.operations.some((operation) => !declared(capability).includes(operation)))
+                    return refuse("not_declared");
+                const scope = permissionCatalog[capability].scope;
+                if (grant !== null &&
+                    grant.resources !== "tenant-scope" &&
+                    (scope === null ||
+                        grant.resources.some((resource) => resource.kind !== scope)))
+                    return refuse("invalid_command");
+            }
+            const changed = new Map(command.changes.map((change) => [change.capability, change.grant]));
+            grants = [
+                ...grants.filter((grant) => !changed.has(grant.capability)),
+                ...command.changes.flatMap(({ capability, grant }) => grant === null ||
+                    (grant.resources !== "tenant-scope" && grant.resources.length === 0)
+                    ? []
+                    : [{ capability, ...grant, capabilityApproved: true }]),
+            ];
+            break;
+        }
+        case "select-release":
+            grants = grants
+                .filter((grant) => context.declaration.capabilities.includes(grant.capability))
+                .map((grant) => ({
+                ...grant,
+                operations: grant.operations.filter((operation) => declared(grant.capability).includes(operation)),
+            }));
+            break;
+        case "delete":
+            grants = [];
+            break;
+    }
+    if (grants.length === 0)
+        approval = null;
+    else if (command.kind === "install" || command.kind === "change-grants") {
+        approval = {
+            by: context.principal.actor,
+            at: context.now,
+            authorityVersion: version,
+        };
+    }
+    return Result.succeed({
+        authorityVersion: version,
+        declaredOperationsDigest: context.declaredOperations.digest,
+        approvedGrants: grants,
+        approval,
+    });
+}
 const anonymousMethodsSchema = z
     .array(z
     .strictObject({
@@ -96,7 +203,7 @@ const anonymousMethodsSchema = z
 }), "Anonymous method identities must have unique, sorted names")
     .readonly();
 /** Immutable operation facts derived from descriptor methods and the binding registry. */
-export const declaredOperationsSchema = z.strictObject({
+export const declaredOperationsSchema = z.lazy(() => z.strictObject({
     artifactDigest: ownerCodec(sha256DigestSchema),
     digest: ownerCodec(sha256DigestSchema),
     anonymousMethods: anonymousMethodsSchema,
@@ -108,7 +215,7 @@ export const declaredOperationsSchema = z.strictObject({
     })
         .readonly())
         .readonly(),
-});
+}));
 /** Resolved immutable Release plus host-owned installation and approval state. */
 export const installationSchema = z
     .strictObject({
@@ -117,12 +224,9 @@ export const installationSchema = z
     appId: ownerCodec(appIdSchema),
     release: ownerCodec(releaseSchema),
     releasePin: z.enum(["pinned", "floating"]),
-    authorityVersion: versionSchema,
+    authority: appAuthoritySchema,
     status: z.enum(["enabled", "disabled", "deleted"]),
     visibility: z.enum(["private", "public"]),
-    declaredOperationsDigest: ownerCodec(sha256DigestSchema),
-    approvedGrants: approvedGrantsSchema,
-    approval: approvalSchema.nullable(),
     approvedAnonymousMethods: anonymousMethodsSchema,
     anonymousApproval: approvalSchema.nullable(),
 })
@@ -134,18 +238,17 @@ export const installationSchema = z
         : installation.status !== "deleted" &&
             installation.approvedAnonymousMethods.length > 0 &&
             approval.by.kind === "member" &&
-            approval.authorityVersion <= installation.authorityVersion;
+            approval.authorityVersion <= installation.authority.authorityVersion;
 }, "Anonymous authority requires a retained human approval receipt");
 const releaseFields = {
     release: ownerCodec(releaseSchema),
     releasePin: installationSchema.shape.releasePin,
 };
 /** Host commands; floating targets have already been resolved to immutable Releases. */
-export const installationCommandSchema = z.discriminatedUnion("kind", [
+export const installationCommandSchema = z.lazy(() => z.discriminatedUnion("kind", [
     z.strictObject({
         kind: z.literal("install"),
         ...releaseFields,
-        grants: grantRequestSchema,
     }),
     z.strictObject({ kind: z.literal("select-release"), ...releaseFields }),
     z.strictObject({
@@ -156,14 +259,17 @@ export const installationCommandSchema = z.discriminatedUnion("kind", [
         kind: z.literal("set-visibility"),
         visibility: installationSchema.shape.visibility,
     }),
-    z.strictObject({ kind: z.literal("set-grants"), grants: grantRequestSchema }),
+    z.strictObject({
+        kind: z.literal("change-grants"),
+        changes: grantChangesSchema,
+    }),
     z.strictObject({
         kind: z.literal("approve-anonymous"),
         methods: anonymousMethodsSchema,
     }),
-]);
+]));
 /** Closed refusals: failed commands produce no installation update. */
-export const installationRefusalSchema = z.strictObject({
+export const installationRefusalSchema = z.lazy(() => z.strictObject({
     kind: z.literal("refused"),
     code: z.enum([
         "unavailable",
@@ -173,7 +279,7 @@ export const installationRefusalSchema = z.strictObject({
         "release_app_mismatch",
         "invalid_command",
     ]),
-});
+}));
 /** Pure transition; hosts retain transactions, receipts, epochs and delivery. */
 export function applyInstallationCommand(current, rawCommand, context) {
     const refuse = (code) => Result.fail({ kind: "refused", code });
@@ -190,12 +296,10 @@ export function applyInstallationCommand(current, rawCommand, context) {
             return refuse("stale_authority");
     }
     else if (command.kind === "install" ||
-        context.expectedVersion !== current.authorityVersion) {
+        context.expectedVersion !== current.authority.authorityVersion) {
         return refuse("stale_authority");
     }
-    if ((command.kind === "set-grants" ||
-        (command.kind === "install" && command.grants !== "none")) &&
-        context.role !== "owner")
+    if (command.kind === "change-grants" && context.role !== "owner")
         return refuse("not_owner");
     const anonymousConsent = context.by.kind === "member" &&
         context.anonymousConsent?.memberId === context.by.memberId;
@@ -215,14 +319,38 @@ export function applyInstallationCommand(current, rawCommand, context) {
         release.artifact.artifactDigest ||
         (current !== null &&
             command.kind !== "select-release" &&
-            context.declaredOperations.digest !== current.declaredOperationsDigest))
+            context.declaredOperations.digest !==
+                current.authority.declaredOperationsDigest))
         return refuse("stale_authority");
-    const declared = (capability) => context.declaration.capabilities.includes(capability)
-        ? (context.declaredOperations.capabilities.find((row) => row.capability === capability)?.operations ?? [])
-        : [];
-    const version = (current?.authorityVersion ?? 0) + 1;
-    let grants = current?.approvedGrants ?? [];
-    let approval = current?.approval ?? null;
+    const version = (current?.authority.authorityVersion ?? 0) + 1;
+    const grantCommand = command.kind === "install" || command.kind === "select-release"
+        ? { kind: command.kind }
+        : command.kind === "change-grants"
+            ? command
+            : command.kind === "set-status" && command.status === "deleted"
+                ? { kind: "delete" }
+                : null;
+    const authority = grantCommand === null
+        ? current === null
+            ? Result.fail({
+                kind: "refused",
+                code: "invalid_command",
+            })
+            : Result.succeed({
+                authorityVersion: version,
+                declaredOperationsDigest: current.authority.declaredOperationsDigest,
+                approvedGrants: current.authority.approvedGrants,
+                approval: current.authority.approval,
+            })
+        : applyGrantCommand(current?.authority ?? null, grantCommand, {
+            principal: { actor: context.by, role: context.role },
+            expectedVersion: context.expectedVersion,
+            declaration: context.declaration,
+            declaredOperations: context.declaredOperations,
+            now: context.now,
+        });
+    if (Result.isFailure(authority))
+        return refuse(authority.failure.code);
     let anonymousMethods = current?.approvedAnonymousMethods ?? [];
     let anonymousApproval = current?.anonymousApproval ?? null;
     if (command.kind === "approve-anonymous") {
@@ -239,44 +367,12 @@ export function applyInstallationCommand(current, rawCommand, context) {
                 authorityVersion: version,
             };
     }
-    if (command.kind === "install" || command.kind === "set-grants") {
-        grants =
-            command.grants === "none"
-                ? []
-                : command.grants === "declared"
-                    ? context.declaredOperations.capabilities
-                        .filter((row) => context.declaration.capabilities.includes(row.capability))
-                        .map((row) => ({
-                        ...row,
-                        capabilityApproved: true,
-                        resources: "tenant-scope",
-                    }))
-                    : command.grants.map((grant) => ({
-                        ...grant,
-                        capabilityApproved: true,
-                    }));
-        if (grants.some((grant) => !context.declaration.capabilities.includes(grant.capability) ||
-            grant.operations.some((operation) => !declared(grant.capability).includes(operation))))
-            return refuse("not_declared");
-        approval =
-            command.grants === "none"
-                ? null
-                : { by: context.by, at: context.now, authorityVersion: version };
-    }
     if (command.kind === "select-release") {
         anonymousMethods = anonymousMethods.filter((method) => context.declaredOperations.anonymousMethods.some((declared) => declared.name === method.name && declared.digest === method.digest));
         if (anonymousMethods.length === 0)
             anonymousApproval = null;
-        grants = grants
-            .map((grant) => ({
-            ...grant,
-            operations: grant.operations.filter((operation) => declared(grant.capability).includes(operation)),
-        }))
-            .filter((grant) => context.declaration.capabilities.includes(grant.capability));
     }
     if (command.kind === "set-status" && command.status === "deleted") {
-        grants = [];
-        approval = null;
         anonymousMethods = [];
         anonymousApproval = null;
     }
@@ -288,16 +384,13 @@ export function applyInstallationCommand(current, rawCommand, context) {
         releasePin: command.kind === "install" || command.kind === "select-release"
             ? command.releasePin
             : current?.releasePin,
-        authorityVersion: version,
         status: command.kind === "set-status"
             ? command.status
             : (current?.status ?? "enabled"),
         visibility: command.kind === "set-visibility"
             ? command.visibility
             : (current?.visibility ?? "private"),
-        declaredOperationsDigest: context.declaredOperations.digest,
-        approvedGrants: grants,
-        approval,
+        authority: authority.success,
         approvedAnonymousMethods: anonymousMethods,
         anonymousApproval,
     });
@@ -305,3 +398,17 @@ export function applyInstallationCommand(current, rawCommand, context) {
         ? Result.succeed({ next: next.data, authorityChanged: true })
         : refuse("invalid_command");
 }
+/** Only the committed installation may activate this exact owner selection. */
+export function isCommittedInstallation(current, state, release) {
+    return (current !== null &&
+        state.owner.kind === "installation" &&
+        current.installationId === state.owner.id &&
+        current.instanceId === state.instanceId &&
+        current.appId === state.appId &&
+        current.authority.authorityVersion === state.authorityVersion &&
+        current.status === state.status &&
+        current.release.releaseId === state.releaseId &&
+        release.releaseId === state.releaseId &&
+        release.appId === state.appId &&
+        current.release.artifact.artifactDigest === release.artifact.artifactDigest);
+}