@fungi.computer/oyster 0.28.1 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +4 -0
  2. package/dist/apps/catalog.js +1 -1
  3. package/dist/apps/gate.d.ts +2 -1
  4. package/dist/apps/gate.js +10 -7
  5. package/dist/apps/index.d.ts +1 -1
  6. package/dist/apps/index.js +1 -1
  7. package/dist/apps/installation.d.ts +27 -5
  8. package/dist/apps/installation.js +86 -29
  9. package/dist/apps/operations.d.ts +5 -0
  10. package/dist/apps/operations.js +49 -10
  11. package/dist/apps/permissions.d.ts +23 -7
  12. package/dist/apps/permissions.js +5 -1
  13. package/dist/authorization.d.ts +2 -1
  14. package/dist/boot-host-script.js +1 -1
  15. package/dist/build/candidate-cli.mjs +1823 -1833
  16. package/dist/embed-metafiles.js +2 -2
  17. package/dist/embed-scripts.js +1 -1
  18. package/dist/host.js +7 -2
  19. package/dist/installation-migration.d.ts +5 -0
  20. package/dist/installation-migration.js +78 -0
  21. package/dist/installation-operations.d.ts +8 -0
  22. package/dist/installation-operations.js +2 -0
  23. package/dist/invocation.d.ts +3 -3
  24. package/dist/page-script.js +2 -2
  25. package/dist/standalone/computer.d.ts +2 -2
  26. package/dist/standalone/registry.d.ts +2 -2
  27. package/dist/standalone/workflow-host.d.ts +6 -1
  28. package/dist/tenancy/cloudflare/registry.js +6 -2
  29. package/dist/tenancy/contracts.d.ts +4 -3
  30. package/dist/tenancy/index.js +2 -1
  31. package/dist/tenant.d.ts +2 -1
  32. package/dist/workers.js +2 -0
  33. package/docs/api/apps.md +108 -81
  34. package/docs/api/authorization.md +1 -1
  35. package/docs/api/git.md +4 -4
  36. package/docs/api/host.md +8 -2
  37. package/docs/api/invocation.md +87 -87
  38. package/docs/api/mcp.md +16 -16
  39. package/docs/api/tenancy.md +3 -3
  40. package/docs/api/tenant.md +1 -1
  41. package/docs/api/workers-git.md +157 -157
  42. package/docs/api/workers.md +231 -221
  43. package/package.json +17 -17
package/README.md CHANGED
@@ -248,6 +248,10 @@ owner-only: a browser signs in only with the owner key, and named keys sign in
248
248
  only by header, for MCP, git and the API. The same Worker runs on Cloudflare
249
249
  Workers and on celld, a Workers-compatible runtime you can host yourself.
250
250
 
251
+ Hosts that run teams on this installation model let an owner or an admin approve
252
+ an App's permissions; a member can install but not approve, and the refusal is
253
+ `not_approver`. Standalone Oyster has only the owner, so it behaves as before.
254
+
251
255
  ## Install
252
256
 
253
257
  ```sh
@@ -15,7 +15,7 @@ export const permissionCatalog = {
15
15
  approvals: entry("apps", "Review approvals",
16
16
  // Interim plain consent; the product decision on approvals stays with Levi.
17
17
  "This App can approve or deny your Agents' pending actions as you, and turn on automatic approval.", "list", "ask"),
18
- "agent.list": entry("agents", "List Agents", "see which Agents are available.", "listAgents", "install"),
18
+ "agent.list": entry("agents", "List Agents", "see which Agents are available.", "listAgents", "install", "agent"),
19
19
  "agent.manage": entry("agents", "Create and manage Agents", "create Agents and manage their sessions.", "createAgents", "install", "agent"),
20
20
  "agent.rename": entry("agents", "Rename Agents", "rename Agents you created.", "createAgents", "install"),
21
21
  "agent.avatar": entry("agents", "Change Agent avatars", "change the avatars of Agents you created.", "createAgents", "install"),
@@ -1,3 +1,4 @@
1
+ import type { TeamRole } from "@fungi.computer/cairn/team-role";
1
2
  import * as z from "zod";
2
3
  import { type AppApi, type AppDeclaration, type HostActor } from "@fungi.computer/puffball/app";
3
4
  import { type AppToolAccess } from "./tools.js";
@@ -5,7 +6,7 @@ import { type ResourceRef, type DeclaredOperations, type Installation, type Appr
5
6
  /** Attested by the host, never authenticated by decoding request JSON. */
6
7
  export type HostPrincipal = Readonly<{
7
8
  actor: HostActor;
8
- role: "owner" | "member" | null;
9
+ role: TeamRole | null;
9
10
  }>;
10
11
  /** Requests select existing SDK methods, opaque backend calls and derived operation identities. */
11
12
  export declare const gateRequestSchema: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodObject<{
package/dist/apps/gate.js CHANGED
@@ -1,11 +1,11 @@
1
1
  import { AppInstanceError } from "../index.js";
2
2
  import { appMethodSchemas } from "@fungi.computer/forage";
3
- import { bindingOperationKey } from "./operations.js";
3
+ import { bindingOperationFingerprint, bindingOperationKey, } from "./operations.js";
4
4
  import * as z from "zod";
5
5
  import * as Schema from "effect/Schema";
6
6
  import { appBackendBindingKinds, appBackendBindingOperation, scopeOperationToMethod, appApiMethodNameSchema, appBackendBindingsSchema, appCapabilityIdSchema, } from "@fungi.computer/puffball/app";
7
7
  import { appToolAccessSchema } from "./tools.js";
8
- import { ownerCodec, resourceRefSchema, } from "./installation.js";
8
+ import { ownerCodec, resourceRefSchema, carryGrant, unstampedFingerprint, } from "./installation.js";
9
9
  const bindingNameSchema = ownerCodec(Schema.Literals(Object.values(appBackendBindingKinds).map((kind) => kind.name)));
10
10
  /** Requests select existing SDK methods, opaque backend calls and derived operation identities. */
11
11
  export const gateRequestSchema = z.lazy(() => z.discriminatedUnion("kind", [
@@ -76,13 +76,15 @@ export function grantsFor(installation, declaration, snapshot, capability, resou
76
76
  !declaration.capabilities.includes(capability))
77
77
  return null;
78
78
  const approved = installation.authority.approvedGrants.find((grant) => grant.capability === capability);
79
- const declared = snapshot.capabilities.find((row) => row.capability === capability)
80
- ?.operations ?? [];
81
79
  if (!approved?.capabilityApproved ||
82
80
  !grantsResource(approved.resources, resource))
83
81
  return null;
84
- const operations = approved.operations.filter((operation) => declared.includes(operation));
85
- return { ...approved, operations };
82
+ return carryGrant(approved, snapshot);
83
+ }
84
+ /** A stored fingerprint covers the registry's current one, or awaits its first stamp. */
85
+ function approvedFingerprintMatches(stored, current) {
86
+ return (stored === unstampedFingerprint ||
87
+ (stored !== undefined && stored === current));
86
88
  }
87
89
  /** Approved binding operations from an already verified declaration. Hosts still pin
88
90
  * the selection/version/artifact and compare running frame grants as a subset. */
@@ -100,7 +102,8 @@ export function approvedBindingGrants(installation, declaration, resource = "any
100
102
  return (declaration.capabilities.includes(capability) &&
101
103
  approved?.capabilityApproved &&
102
104
  grantsResource(approved.resources, resource) &&
103
- approved.operations.includes(bindingOperationKey(binding.name, name)));
105
+ approved.operations.includes(bindingOperationKey(binding.name, name)) &&
106
+ approvedFingerprintMatches(approved.fingerprints[bindingOperationKey(binding.name, name)], bindingOperationFingerprint(binding.name, name)));
104
107
  }));
105
108
  });
106
109
  if (operations.length > 0)
@@ -1,5 +1,5 @@
1
1
  /** Installation records and pure admission rules; tenant state and commits stay host-owned. */
2
- export { applyGrantCommand, appAuthoritySchema, grantCommandSchema, type AppAuthority, type GrantCommand, type GrantContext, type GrantRefusal, applyInstallationCommand, approvedGrantSchema, declaredOperationsSchema, installationCommandSchema, installationIdSchema, installationRefusalSchema, installationSchema, type Approval, type ApprovedGrant, type CapabilityOperationDescriptor, type DeclaredOperations, grantChangeSchema, type GrantChange, type Installation, type InstallationCommand, type InstallationContext, type InstallationReader, type InstallationRefusal, type InstallationUpdate, type ResourceRef, } from "./installation.js";
2
+ export { applyGrantCommand, appAuthoritySchema, grantCommandSchema, type AppAuthority, type GrantCommand, type GrantContext, type GrantRefusal, applyInstallationCommand, approvedGrantSchema, declaredOperationsSchema, installationCommandSchema, installationIdSchema, installationRefusalSchema, installationSchema, type Approval, type ApprovedGrant, type CapabilityOperationDescriptor, type DeclaredOperations, grantChangeSchema, type GrantChange, type Installation, type InstallationCommand, type InstallationContext, type InstallationReader, type InstallationRefusal, type InstallationUpdate, type ResourceRef, unstampedFingerprint, } from "./installation.js";
3
3
  export { permissionPinsSchema, permissionSaveSchema, type PermissionPins, appPermissionsWireSchema, appPermissionPageSchema, permissionScreen, draftOf, editPermissions, planGrantChange, rebaseDraft, type PermissionDraft, type PermissionEdit, type PermissionScreen, type AppPermissionsWire, type AppPermissionsPort, type AppPermissionsViewData, grantRequestFor, pendingCapabilities, type GrantRequestDecision, type ResourceOption, } from "./permissions.js";
4
4
  export { admits, admitMethodMetadata, appInvocationCeiling, approvedBindingGrants, scopedBindings, grantsFor, gateRefusalSchema, gateRequestSchema, invocationGrantsSchema, type AppMethodDeclaration, type AppMethodMetadataDecision, type GateDecision, type GateFacts, type GateRequest, type HostPrincipal, type InvocationGrants, } from "./gate.js";
5
5
  export { deriveDeclaredOperations, appCallOperation } from "./operations.js";
@@ -1,5 +1,5 @@
1
1
  /** Installation records and pure admission rules; tenant state and commits stay host-owned. */
2
- export { applyGrantCommand, appAuthoritySchema, grantCommandSchema, applyInstallationCommand, approvedGrantSchema, declaredOperationsSchema, installationCommandSchema, installationIdSchema, installationRefusalSchema, installationSchema, grantChangeSchema, } from "./installation.js";
2
+ export { applyGrantCommand, appAuthoritySchema, grantCommandSchema, applyInstallationCommand, approvedGrantSchema, declaredOperationsSchema, installationCommandSchema, installationIdSchema, installationRefusalSchema, installationSchema, grantChangeSchema, unstampedFingerprint, } from "./installation.js";
3
3
  export { permissionPinsSchema, permissionSaveSchema, appPermissionsWireSchema, appPermissionPageSchema, permissionScreen, draftOf, editPermissions, planGrantChange, rebaseDraft, grantRequestFor, pendingCapabilities, } from "./permissions.js";
4
4
  export { admits, admitMethodMetadata, appInvocationCeiling, approvedBindingGrants, scopedBindings, grantsFor, gateRefusalSchema, gateRequestSchema, invocationGrantsSchema, } from "./gate.js";
5
5
  export { deriveDeclaredOperations, appCallOperation } from "./operations.js";
@@ -1,3 +1,4 @@
1
+ import { type TeamRole } from "@fungi.computer/cairn/team-role";
1
2
  import * as z from "zod";
2
3
  import * as Schema from "effect/Schema";
3
4
  import * as Result from "effect/Result";
@@ -15,11 +16,21 @@ export declare const resourceRefSchema: z.ZodLazy<z.ZodReadonly<z.ZodObject<{
15
16
  id: z.ZodString;
16
17
  }, z.core.$strict>>>;
17
18
  export type ResourceRef = Exclude<ApprovedGrant["resources"], "tenant-scope">[number];
19
+ /**
20
+ * Stands in for the fingerprint of an operation approved before fingerprints
21
+ * existed. The storage migration writes it; the first snapshot that carries the
22
+ * operation by name replaces it with the declared fingerprint (`carryGrant`).
23
+ */
24
+ export declare const unstampedFingerprint = "unstamped";
18
25
  /**
19
26
  * Consent approves capabilities, with explicit operation and resource ceilings.
20
27
  * A Release adding a method that requires an already-approved capability needs
21
28
  * no new consent; a new capability does. Release selection intersects stored
22
- * operations instead of adding approvals. Each Worker call is still restricted
29
+ * operations instead of adding approvals: an operation carries only when its
30
+ * name and its fingerprint (the host descriptor method entry, or the binding
31
+ * operation, that defines what it does) both match the approval, so a
32
+ * same-named operation whose behavior changed needs approval again, as a new
33
+ * operation does. Each Worker call is still restricted
23
34
  * to that method's declared requires, never the App's complete capability set.
24
35
  * Only an approved install or change-grants command mints capabilityApproved.
25
36
  * Empty operation rows retain that consent; removing the capability revokes it.
@@ -31,6 +42,7 @@ export declare const approvedGrantSchema: z.ZodReadonly<z.ZodObject<{
31
42
  capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.instructions" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage", unknown>>;
32
43
  capabilityApproved: z.ZodLiteral<true>;
33
44
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
45
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
34
46
  resources: z.ZodUnion<readonly [z.ZodLiteral<"tenant-scope">, z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
35
47
  kind: z.ZodString;
36
48
  id: z.ZodString;
@@ -63,6 +75,7 @@ export declare const appAuthoritySchema: z.ZodObject<{
63
75
  capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.instructions" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage", unknown>>;
64
76
  capabilityApproved: z.ZodLiteral<true>;
65
77
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
78
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
66
79
  resources: z.ZodUnion<readonly [z.ZodLiteral<"tenant-scope">, z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
67
80
  kind: z.ZodString;
68
81
  id: z.ZodString;
@@ -115,8 +128,15 @@ export type GrantContext = Readonly<{
115
128
  }>;
116
129
  export type GrantRefusal = Readonly<{
117
130
  kind: "refused";
118
- code: "stale_authority" | "not_owner" | "not_declared" | "invalid_command";
131
+ code: "stale_authority" | "not_approver" | "not_declared" | "invalid_command";
119
132
  }>;
133
+ /**
134
+ * The part of a stored approval the current declaration still covers: an
135
+ * operation carries only when it is declared and its stored fingerprint equals
136
+ * the declared one (or it was approved before fingerprints existed and is
137
+ * stamped now). Everything else needs the owner's approval again.
138
+ */
139
+ export declare function carryGrant(grant: ApprovedGrant, declared: DeclaredOperations): ApprovedGrant;
120
140
  /** One host-independent approval policy; selection only intersects existing grants. */
121
141
  export declare function applyGrantCommand(current: AppAuthority | null, rawCommand: GrantCommand, context: GrantContext): Result.Result<AppAuthority, GrantRefusal>;
122
142
  /** Immutable operation facts derived from descriptor methods and the binding registry. */
@@ -126,11 +146,12 @@ export declare const declaredOperationsSchema: z.ZodLazy<z.ZodObject<{
126
146
  capabilities: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
127
147
  capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.instructions" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage", unknown>>;
128
148
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
149
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
129
150
  }, z.core.$strict>>>>;
130
151
  }, z.core.$strict>>;
131
152
  export type DeclaredOperations = Readonly<z.output<typeof declaredOperationsSchema>>;
132
153
  /** Use the existing adapter's permission and methods; hosts author no operation lists. */
133
- export type CapabilityOperationDescriptor = Pick<CapabilityDescriptor, "id" | "methods"> & Readonly<{
154
+ export type CapabilityOperationDescriptor = Pick<CapabilityDescriptor, "id" | "base" | "methods"> & Readonly<{
134
155
  permission: ApprovedGrant["capability"];
135
156
  }>;
136
157
  /** Resolved immutable Release plus host-owned installation and approval state. */
@@ -162,6 +183,7 @@ export declare const installationSchema: z.ZodObject<{
162
183
  capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.instructions" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage", unknown>>;
163
184
  capabilityApproved: z.ZodLiteral<true>;
164
185
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
186
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
165
187
  resources: z.ZodUnion<readonly [z.ZodLiteral<"tenant-scope">, z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
166
188
  kind: z.ZodString;
167
189
  id: z.ZodString;
@@ -252,7 +274,7 @@ export type InstallationCommand = z.output<typeof installationCommandSchema>;
252
274
  /** Values captured by the host; identities and time are never generated by the reducer. */
253
275
  export type InstallationContext = Readonly<{
254
276
  by: HostActor;
255
- role: "owner" | "member" | null;
277
+ role: TeamRole | null;
256
278
  expectedVersion: number | null;
257
279
  declaration: AppDeclaration;
258
280
  declaredOperations: DeclaredOperations;
@@ -269,7 +291,7 @@ export declare const installationRefusalSchema: z.ZodLazy<z.ZodObject<{
269
291
  stale_authority: "stale_authority";
270
292
  not_declared: "not_declared";
271
293
  release_app_mismatch: "release_app_mismatch";
272
- not_owner: "not_owner";
294
+ not_approver: "not_approver";
273
295
  invalid_command: "invalid_command";
274
296
  }>;
275
297
  }, z.core.$strict>>;
@@ -1,3 +1,4 @@
1
+ import { teamRoleAtLeast, } from "@fungi.computer/cairn/team-role";
1
2
  import * as z from "zod";
2
3
  import * as Schema from "effect/Schema";
3
4
  import * as Result from "effect/Result";
@@ -33,11 +34,23 @@ const operationsSchema = z.lazy(() => z
33
34
  .array(z.string().min(1))
34
35
  .refine((values) => new Set(values).size === values.length, "Operations must be unique")
35
36
  .readonly());
37
+ /**
38
+ * Stands in for the fingerprint of an operation approved before fingerprints
39
+ * existed. The storage migration writes it; the first snapshot that carries the
40
+ * operation by name replaces it with the declared fingerprint (`carryGrant`).
41
+ */
42
+ export const unstampedFingerprint = "unstamped";
43
+ /** Operation name to the fingerprint of the data defining what it does. */
44
+ const fingerprintsSchema = z.lazy(() => z.record(z.string().min(1), z.string().min(1)).readonly());
36
45
  /**
37
46
  * Consent approves capabilities, with explicit operation and resource ceilings.
38
47
  * A Release adding a method that requires an already-approved capability needs
39
48
  * no new consent; a new capability does. Release selection intersects stored
40
- * operations instead of adding approvals. Each Worker call is still restricted
49
+ * operations instead of adding approvals: an operation carries only when its
50
+ * name and its fingerprint (the host descriptor method entry, or the binding
51
+ * operation, that defines what it does) both match the approval, so a
52
+ * same-named operation whose behavior changed needs approval again, as a new
53
+ * operation does. Each Worker call is still restricted
41
54
  * to that method's declared requires, never the App's complete capability set.
42
55
  * Only an approved install or change-grants command mints capabilityApproved.
43
56
  * Empty operation rows retain that consent; removing the capability revokes it.
@@ -50,6 +63,8 @@ export const approvedGrantSchema = z
50
63
  capability: ownerCodec(appCapabilityIdSchema),
51
64
  capabilityApproved: z.literal(true),
52
65
  operations: operationsSchema,
66
+ /** Fingerprint of each approved operation as declared when the owner approved it. */
67
+ fingerprints: fingerprintsSchema,
53
68
  resources: z.union([
54
69
  z.literal("tenant-scope"),
55
70
  z.array(resourceRefSchema).readonly(),
@@ -60,6 +75,11 @@ export const approvedGrantSchema = z
60
75
  const approvedGrantsSchema = z.lazy(() => z
61
76
  .array(approvedGrantSchema)
62
77
  .refine((grants) => new Set(grants.map((grant) => grant.capability)).size === grants.length, "Capabilities must be unique")
78
+ .refine((grants) => grants.every((grant) => {
79
+ const names = Object.keys(grant.fingerprints);
80
+ return (names.length === grant.operations.length &&
81
+ grant.operations.every((operation) => names.includes(operation)));
82
+ }), "Every approved operation needs exactly one fingerprint")
63
83
  .readonly());
64
84
  /** A bounded owner edit. Unnamed approvals are not part of the command. */
65
85
  export const grantChangeSchema = z
@@ -67,7 +87,11 @@ export const grantChangeSchema = z
67
87
  capability: ownerCodec(appCapabilityIdSchema),
68
88
  grant: approvedGrantSchema
69
89
  .unwrap()
70
- .omit({ capabilityApproved: true, capability: true })
90
+ .omit({
91
+ capabilityApproved: true,
92
+ capability: true,
93
+ fingerprints: true,
94
+ })
71
95
  .readonly()
72
96
  .nullable(),
73
97
  })
@@ -103,6 +127,36 @@ export const grantCommandSchema = z.discriminatedUnion("kind", [
103
127
  z.strictObject({ kind: z.literal("select-release") }),
104
128
  z.strictObject({ kind: z.literal("delete") }),
105
129
  ]);
130
+ /** Owners and admins approve App permissions; members manage installs only. */
131
+ const approves = (role) => role !== null && teamRoleAtLeast(role, "admin");
132
+ const declaredRow = (declared, capability) => declared.capabilities.find((row) => row.capability === capability);
133
+ /** Fingerprints the declaration currently assigns to these operations. */
134
+ function fingerprintsOf(declared, capability, operations) {
135
+ const row = declaredRow(declared, capability);
136
+ return Object.fromEntries(operations.flatMap((operation) => {
137
+ const fingerprint = row?.operations.includes(operation)
138
+ ? row.fingerprints[operation]
139
+ : undefined;
140
+ return fingerprint === undefined ? [] : [[operation, fingerprint]];
141
+ }));
142
+ }
143
+ /**
144
+ * The part of a stored approval the current declaration still covers: an
145
+ * operation carries only when it is declared and its stored fingerprint equals
146
+ * the declared one (or it was approved before fingerprints existed and is
147
+ * stamped now). Everything else needs the owner's approval again.
148
+ */
149
+ export function carryGrant(grant, declared) {
150
+ const current = fingerprintsOf(declared, grant.capability, grant.operations);
151
+ const operations = grant.operations.filter((operation) => current[operation] !== undefined &&
152
+ (grant.fingerprints[operation] === unstampedFingerprint ||
153
+ current[operation] === grant.fingerprints[operation]));
154
+ return {
155
+ ...grant,
156
+ operations,
157
+ fingerprints: fingerprintsOf(declared, grant.capability, operations),
158
+ };
159
+ }
106
160
  /** One host-independent approval policy; selection only intersects existing grants. */
107
161
  export function applyGrantCommand(current, rawCommand, context) {
108
162
  const refuse = (code) => Result.fail({ kind: "refused", code });
@@ -116,27 +170,27 @@ export function applyGrantCommand(current, rawCommand, context) {
116
170
  if ((context.expectedVersion ?? 0) !== (current?.authorityVersion ?? 0))
117
171
  return refuse("stale_authority");
118
172
  if (context.principal.role === null ||
119
- (command.kind === "change-grants" && context.principal.role !== "owner"))
120
- return refuse("not_owner");
173
+ (command.kind === "change-grants" && !approves(context.principal.role)))
174
+ return refuse("not_approver");
121
175
  const declared = (capability) => context.declaredOperations.capabilities.find((row) => row.capability === capability)?.operations ?? [];
122
176
  const version = (current?.authorityVersion ?? 0) + 1;
123
177
  let grants = current?.approvedGrants ?? [];
124
178
  let approval = current?.approval ?? null;
125
179
  switch (command.kind) {
126
180
  case "install":
127
- grants =
128
- context.principal.role === "owner"
129
- ? context.declaration.capabilities
130
- .filter((capability) => permissionCatalog[capability].consent === "install" ||
131
- (capability === "team.workbenchHost" &&
132
- context.builtInShell === true))
133
- .map((capability) => ({
134
- capability,
135
- capabilityApproved: true,
136
- operations: declared(capability),
137
- resources: "tenant-scope",
138
- }))
139
- : [];
181
+ grants = approves(context.principal.role)
182
+ ? context.declaration.capabilities
183
+ .filter((capability) => permissionCatalog[capability].consent === "install" ||
184
+ (capability === "team.workbenchHost" &&
185
+ context.builtInShell === true))
186
+ .map((capability) => ({
187
+ capability,
188
+ capabilityApproved: true,
189
+ operations: declared(capability),
190
+ fingerprints: fingerprintsOf(context.declaredOperations, capability, declared(capability)),
191
+ resources: "tenant-scope",
192
+ }))
193
+ : [];
140
194
  break;
141
195
  case "change-grants": {
142
196
  for (const { capability, grant } of command.changes) {
@@ -154,24 +208,25 @@ export function applyGrantCommand(current, rawCommand, context) {
154
208
  grants = [
155
209
  ...grants
156
210
  .filter((grant) => !changed.has(grant.capability))
157
- .map((grant) => ({
158
- ...grant,
159
- operations: grant.operations.filter((operation) => declared(grant.capability).includes(operation)),
160
- })),
211
+ .map((grant) => carryGrant(grant, context.declaredOperations)),
161
212
  ...command.changes.flatMap(({ capability, grant }) => grant === null ||
162
213
  (grant.resources !== "tenant-scope" && grant.resources.length === 0)
163
214
  ? []
164
- : [{ capability, ...grant, capabilityApproved: true }]),
215
+ : [
216
+ {
217
+ capability,
218
+ ...grant,
219
+ fingerprints: fingerprintsOf(context.declaredOperations, capability, grant.operations),
220
+ capabilityApproved: true,
221
+ },
222
+ ]),
165
223
  ];
166
224
  break;
167
225
  }
168
226
  case "select-release":
169
227
  grants = grants
170
228
  .filter((grant) => context.declaration.capabilities.includes(grant.capability))
171
- .map((grant) => ({
172
- ...grant,
173
- operations: grant.operations.filter((operation) => declared(grant.capability).includes(operation)),
174
- }));
229
+ .map((grant) => carryGrant(grant, context.declaredOperations));
175
230
  break;
176
231
  case "delete":
177
232
  grants = [];
@@ -202,6 +257,8 @@ export const declaredOperationsSchema = z.lazy(() => z.strictObject({
202
257
  .strictObject({
203
258
  capability: ownerCodec(appCapabilityIdSchema),
204
259
  operations: operationsSchema,
260
+ /** What each operation does, from its host descriptor method or binding operation. */
261
+ fingerprints: fingerprintsSchema,
205
262
  })
206
263
  .readonly())
207
264
  .readonly(),
@@ -244,7 +301,7 @@ export const installationRefusalSchema = z.lazy(() => z.strictObject({
244
301
  code: z.enum([
245
302
  "unavailable",
246
303
  "stale_authority",
247
- "not_owner",
304
+ "not_approver",
248
305
  "not_declared",
249
306
  "release_app_mismatch",
250
307
  "invalid_command",
@@ -269,8 +326,8 @@ export function applyInstallationCommand(current, rawCommand, context) {
269
326
  context.expectedVersion !== current.authority.authorityVersion) {
270
327
  return refuse("stale_authority");
271
328
  }
272
- if (command.kind === "change-grants" && context.role !== "owner")
273
- return refuse("not_owner");
329
+ if (command.kind === "change-grants" && !approves(context.role))
330
+ return refuse("not_approver");
274
331
  const release = command.kind === "install" || command.kind === "select-release"
275
332
  ? command.release
276
333
  : current?.release;
@@ -4,5 +4,10 @@ import { type CapabilityOperationDescriptor, type DeclaredOperations, type Insta
4
4
  export declare function bindingOperationKey(binding: AppBackendBindingName, operation: string): string;
5
5
  /** Approval identity for one UI-side target method; upgrades intersect these exact pairs. */
6
6
  export declare function appCallOperation(appId: string, method: string): string;
7
+ /**
8
+ * What a backend binding operation does: the broker class, effect and required
9
+ * capabilities from Puffball's registry. Null for an operation the registry lacks.
10
+ */
11
+ export declare function bindingOperationFingerprint(binding: AppBackendBindingName, operation: string): string | null;
7
12
  /** Sole derivation owner. Inputs are the verified Release declaration and existing host adapters. */
8
13
  export declare function deriveDeclaredOperations(release: Installation["release"], declaration: AppDeclaration, descriptors: readonly CapabilityOperationDescriptor[]): Promise<DeclaredOperations>;
@@ -9,28 +9,60 @@ export function bindingOperationKey(binding, operation) {
9
9
  export function appCallOperation(appId, method) {
10
10
  return `route:apps.call:${appId}:${method}`;
11
11
  }
12
+ /**
13
+ * What a backend binding operation does: the broker class, effect and required
14
+ * capabilities from Puffball's registry. Null for an operation the registry lacks.
15
+ */
16
+ export function bindingOperationFingerprint(binding, operation) {
17
+ const definition = appBackendBindingOperation(binding, operation);
18
+ return definition === undefined
19
+ ? null
20
+ : JSON.stringify([
21
+ definition.cap,
22
+ definition.effect,
23
+ [...definition.requires].sort(),
24
+ ]);
25
+ }
26
+ /** What a host route operation does: where its descriptor method entry sends the call. */
27
+ function routeFingerprint(descriptor, method) {
28
+ return JSON.stringify([
29
+ descriptor.base,
30
+ method.kind,
31
+ method.method,
32
+ method.path,
33
+ ]);
34
+ }
35
+ /**
36
+ * Operations the signed declaration alone defines (`apps.call` targets and the
37
+ * `route:app.methods:*` approval-detail rows) have nothing host-side to change.
38
+ */
39
+ const declarationFingerprint = JSON.stringify(["declaration"]);
12
40
  /** Sole derivation owner. Inputs are the verified Release declaration and existing host adapters. */
13
41
  export async function deriveDeclaredOperations(release, declaration, descriptors) {
14
42
  if (descriptors.some((descriptor) => descriptor.id === "app.methods"))
15
43
  throw new Error("app_methods_descriptor_reserved");
16
44
  const capabilities = new Map(declaration.capabilities.map((capability) => [
17
45
  capability,
18
- new Set(),
46
+ new Map(),
19
47
  ]));
20
48
  for (const call of declaration.calls ?? [])
21
49
  for (const method of call.methods)
22
- capabilities.get("apps.call")?.add(appCallOperation(call.appId, method));
50
+ capabilities
51
+ .get("apps.call")
52
+ ?.set(appCallOperation(call.appId, method), declarationFingerprint);
23
53
  for (const [name, method] of Object.entries(declaration.api?.methods ?? {}))
24
54
  for (const capability of method.requires)
25
- capabilities.get(capability)?.add(`route:app.methods:${name}`);
55
+ capabilities
56
+ .get(capability)
57
+ ?.set(`route:app.methods:${name}`, declarationFingerprint);
26
58
  const routes = descriptors
27
59
  .filter((descriptor) => capabilities.has(descriptor.permission))
28
60
  .map((descriptor) => {
29
61
  const methods = Object.entries(descriptor.methods).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
30
- for (const [name] of methods)
62
+ for (const [name, method] of methods)
31
63
  capabilities
32
64
  .get(descriptor.permission)
33
- ?.add(`route:${descriptor.id}:${name}`);
65
+ ?.set(`route:${descriptor.id}:${name}`, routeFingerprint(descriptor, method));
34
66
  return { id: descriptor.id, permission: descriptor.permission, methods };
35
67
  })
36
68
  .sort((a, b) => a.id < b.id
@@ -47,10 +79,13 @@ export async function deriveDeclaredOperations(release, declaration, descriptors
47
79
  const operation = appBackendBindingOperation(binding.name, name);
48
80
  if (!operation?.requires.every((capability) => capabilities.has(capability)))
49
81
  return [];
82
+ const fingerprint = bindingOperationFingerprint(binding.name, name);
83
+ if (fingerprint === null)
84
+ return [];
50
85
  for (const capability of operation.requires)
51
86
  capabilities
52
87
  .get(capability)
53
- ?.add(bindingOperationKey(binding.name, name));
88
+ ?.set(bindingOperationKey(binding.name, name), fingerprint);
54
89
  return [
55
90
  {
56
91
  binding: binding.name,
@@ -69,10 +104,14 @@ export async function deriveDeclaredOperations(release, declaration, descriptors
69
104
  : 0);
70
105
  const rows = [...capabilities]
71
106
  .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
72
- .map(([capability, operations]) => ({
73
- capability,
74
- operations: [...operations].sort(),
75
- }));
107
+ .map(([capability, operations]) => {
108
+ const sorted = [...operations].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
109
+ return {
110
+ capability,
111
+ operations: sorted.map(([name]) => name),
112
+ fingerprints: Object.fromEntries(sorted),
113
+ };
114
+ });
76
115
  const artifactDigest = release.artifact.artifactDigest;
77
116
  const digest = await sha256(new TextEncoder().encode(JSON.stringify({
78
117
  artifactDigest,
@@ -3,15 +3,26 @@ import type { AppPermissionRequest } from "@fungi.computer/agar";
3
3
  import { type AppDeclaration, type AppCapabilityId } from "@fungi.computer/puffball/app";
4
4
  import { type PermissionCatalogEntry } from "./catalog.js";
5
5
  import type { SigilName } from "@fungi.computer/sigils";
6
- import { type AppAuthority, type DeclaredOperations, type GrantCommand, type GrantChange, type ResourceRef } from "./installation.js";
6
+ import { type AppAuthority, type ApprovedGrant, type DeclaredOperations, type GrantCommand, type GrantChange, type ResourceRef } from "./installation.js";
7
7
  /** A host-provided resource identity and its display label. */
8
8
  export type ResourceOption = {
9
9
  kind: string;
10
10
  id: string;
11
11
  label: string;
12
12
  };
13
- /** Includes newly declared operations and capabilities the owner has narrowed. */
14
- export declare function pendingCapabilities(authority: Pick<AppAuthority, "approvedGrants">, declaration: Pick<AppDeclaration, "capabilities">, declaredOperations: DeclaredOperations): AppDeclaration["capabilities"];
13
+ /**
14
+ * The approval facts the permission page edits; fingerprints are the host's concern.
15
+ * @inline
16
+ */
17
+ export type ApprovalRows = Readonly<{
18
+ approvedGrants: readonly Pick<ApprovedGrant, "capability" | "operations" | "resources">[];
19
+ }>;
20
+ /**
21
+ * Includes newly declared or changed operations and capabilities the owner has
22
+ * narrowed. The host sends grants already reduced by carryGrant, so a changed
23
+ * operation is absent from them exactly as a new one is.
24
+ */
25
+ export declare function pendingCapabilities(authority: ApprovalRows, declaration: Pick<AppDeclaration, "capabilities">, declaredOperations: DeclaredOperations): AppDeclaration["capabilities"];
15
26
  /** How an App's runtime permission request relates to the owner's stored grants. */
16
27
  export type GrantRequestDecision = Readonly<{
17
28
  kind: "covered";
@@ -64,13 +75,13 @@ export type PermissionEdit = Readonly<{
64
75
  on: boolean;
65
76
  }>;
66
77
  /** The saved operation ceiling is the starting point, including empty operation rows. */
67
- export declare function draftOf(authority: AppAuthority): PermissionDraft;
78
+ export declare function draftOf(authority: ApprovalRows): PermissionDraft;
68
79
  /** An edit changes one capability; unrelated saved operations and scopes are retained. */
69
80
  export declare function editPermissions(draft: PermissionDraft, edit: PermissionEdit, declared: DeclaredOperations): PermissionDraft;
70
81
  /** Only touched capability rows cross the save boundary. */
71
- export declare function planGrantChange(baseline: AppAuthority, draft: PermissionDraft): readonly GrantChange[];
82
+ export declare function planGrantChange(baseline: ApprovalRows, draft: PermissionDraft): readonly GrantChange[];
72
83
  /** A conflict preserves the person's edits while taking fresh untouched capabilities. */
73
- export declare function rebaseDraft(draft: PermissionDraft, baseline: AppAuthority, current: AppAuthority): PermissionDraft;
84
+ export declare function rebaseDraft(draft: PermissionDraft, baseline: ApprovalRows, current: ApprovalRows): PermissionDraft;
74
85
  /** Serializable host facts; the browser derives presentation, never authority. */
75
86
  export declare const appPermissionsWireSchema: z.ZodObject<{
76
87
  authority: z.ZodObject<{
@@ -80,6 +91,7 @@ export declare const appPermissionsWireSchema: z.ZodObject<{
80
91
  capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.instructions" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage", unknown>>;
81
92
  capabilityApproved: z.ZodLiteral<true>;
82
93
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
94
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
83
95
  resources: z.ZodUnion<readonly [z.ZodLiteral<"tenant-scope">, z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
84
96
  kind: z.ZodString;
85
97
  id: z.ZodString;
@@ -106,6 +118,7 @@ export declare const appPermissionsWireSchema: z.ZodObject<{
106
118
  capabilities: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
107
119
  capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.instructions" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage", unknown>>;
108
120
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
121
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
109
122
  }, z.core.$strict>>>>;
110
123
  }, z.core.$strict>>;
111
124
  }, z.core.$strict>;
@@ -155,7 +168,8 @@ export type PermissionScreen = Readonly<{
155
168
  }>[];
156
169
  }>;
157
170
  /** Every declared permission is visible, including removable saved resources no longer listed by the host. */
158
- export declare function permissionScreen(input: AppPermissionsWire & Readonly<{
171
+ export declare function permissionScreen(input: Omit<AppPermissionsWire, "authority"> & Readonly<{
172
+ authority: ApprovalRows;
159
173
  resources: readonly ResourceOption[];
160
174
  canEdit: boolean;
161
175
  }>): PermissionScreen;
@@ -230,6 +244,7 @@ export declare const appPermissionPageSchema: z.ZodObject<{
230
244
  capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.instructions" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage", unknown>>;
231
245
  capabilityApproved: z.ZodLiteral<true>;
232
246
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
247
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
233
248
  resources: z.ZodUnion<readonly [z.ZodLiteral<"tenant-scope">, z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
234
249
  kind: z.ZodString;
235
250
  id: z.ZodString;
@@ -256,6 +271,7 @@ export declare const appPermissionPageSchema: z.ZodObject<{
256
271
  capabilities: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
257
272
  capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.instructions" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage", unknown>>;
258
273
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
274
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
259
275
  }, z.core.$strict>>>>;
260
276
  }, z.core.$strict>>;
261
277
  }, z.core.$strict>;
@@ -2,7 +2,11 @@ import * as z from "zod";
2
2
  import { permissionCatalog } from "./catalog.js";
3
3
  import { sha256DigestSchema } from "@fungi.computer/puffball/effect";
4
4
  import { appAuthoritySchema, declaredOperationsSchema, ownerCodec, grantCommandSchema, } from "./installation.js";
5
- /** Includes newly declared operations and capabilities the owner has narrowed. */
5
+ /**
6
+ * Includes newly declared or changed operations and capabilities the owner has
7
+ * narrowed. The host sends grants already reduced by carryGrant, so a changed
8
+ * operation is absent from them exactly as a new one is.
9
+ */
6
10
  export function pendingCapabilities(authority, declaration, declaredOperations) {
7
11
  return declaration.capabilities.filter((capability) => {
8
12
  if (permissionCatalog[capability].consent === "affordance")