@fungi.computer/oyster 0.28.1 → 0.28.2

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.
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)
@@ -15,11 +15,21 @@ export declare const resourceRefSchema: z.ZodLazy<z.ZodReadonly<z.ZodObject<{
15
15
  id: z.ZodString;
16
16
  }, z.core.$strict>>>;
17
17
  export type ResourceRef = Exclude<ApprovedGrant["resources"], "tenant-scope">[number];
18
+ /**
19
+ * Stands in for the fingerprint of an operation approved before fingerprints
20
+ * existed. The storage migration writes it; the first snapshot that carries the
21
+ * operation by name replaces it with the declared fingerprint (`carryGrant`).
22
+ */
23
+ export declare const unstampedFingerprint = "unstamped";
18
24
  /**
19
25
  * Consent approves capabilities, with explicit operation and resource ceilings.
20
26
  * A Release adding a method that requires an already-approved capability needs
21
27
  * no new consent; a new capability does. Release selection intersects stored
22
- * operations instead of adding approvals. Each Worker call is still restricted
28
+ * operations instead of adding approvals: an operation carries only when its
29
+ * name and its fingerprint (the host descriptor method entry, or the binding
30
+ * operation, that defines what it does) both match the approval, so a
31
+ * same-named operation whose behavior changed needs approval again, as a new
32
+ * operation does. Each Worker call is still restricted
23
33
  * to that method's declared requires, never the App's complete capability set.
24
34
  * Only an approved install or change-grants command mints capabilityApproved.
25
35
  * Empty operation rows retain that consent; removing the capability revokes it.
@@ -31,6 +41,7 @@ export declare const approvedGrantSchema: z.ZodReadonly<z.ZodObject<{
31
41
  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
42
  capabilityApproved: z.ZodLiteral<true>;
33
43
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
44
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
34
45
  resources: z.ZodUnion<readonly [z.ZodLiteral<"tenant-scope">, z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
35
46
  kind: z.ZodString;
36
47
  id: z.ZodString;
@@ -63,6 +74,7 @@ export declare const appAuthoritySchema: z.ZodObject<{
63
74
  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
75
  capabilityApproved: z.ZodLiteral<true>;
65
76
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
77
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
66
78
  resources: z.ZodUnion<readonly [z.ZodLiteral<"tenant-scope">, z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
67
79
  kind: z.ZodString;
68
80
  id: z.ZodString;
@@ -117,6 +129,13 @@ export type GrantRefusal = Readonly<{
117
129
  kind: "refused";
118
130
  code: "stale_authority" | "not_owner" | "not_declared" | "invalid_command";
119
131
  }>;
132
+ /**
133
+ * The part of a stored approval the current declaration still covers: an
134
+ * operation carries only when it is declared and its stored fingerprint equals
135
+ * the declared one (or it was approved before fingerprints existed and is
136
+ * stamped now). Everything else needs the owner's approval again.
137
+ */
138
+ export declare function carryGrant(grant: ApprovedGrant, declared: DeclaredOperations): ApprovedGrant;
120
139
  /** One host-independent approval policy; selection only intersects existing grants. */
121
140
  export declare function applyGrantCommand(current: AppAuthority | null, rawCommand: GrantCommand, context: GrantContext): Result.Result<AppAuthority, GrantRefusal>;
122
141
  /** Immutable operation facts derived from descriptor methods and the binding registry. */
@@ -126,11 +145,12 @@ export declare const declaredOperationsSchema: z.ZodLazy<z.ZodObject<{
126
145
  capabilities: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
127
146
  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
147
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
148
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
129
149
  }, z.core.$strict>>>>;
130
150
  }, z.core.$strict>>;
131
151
  export type DeclaredOperations = Readonly<z.output<typeof declaredOperationsSchema>>;
132
152
  /** Use the existing adapter's permission and methods; hosts author no operation lists. */
133
- export type CapabilityOperationDescriptor = Pick<CapabilityDescriptor, "id" | "methods"> & Readonly<{
153
+ export type CapabilityOperationDescriptor = Pick<CapabilityDescriptor, "id" | "base" | "methods"> & Readonly<{
134
154
  permission: ApprovedGrant["capability"];
135
155
  }>;
136
156
  /** Resolved immutable Release plus host-owned installation and approval state. */
@@ -162,6 +182,7 @@ export declare const installationSchema: z.ZodObject<{
162
182
  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
183
  capabilityApproved: z.ZodLiteral<true>;
164
184
  operations: z.ZodLazy<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
185
+ fingerprints: z.ZodLazy<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
165
186
  resources: z.ZodUnion<readonly [z.ZodLiteral<"tenant-scope">, z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
166
187
  kind: z.ZodString;
167
188
  id: z.ZodString;
@@ -33,11 +33,23 @@ const operationsSchema = z.lazy(() => z
33
33
  .array(z.string().min(1))
34
34
  .refine((values) => new Set(values).size === values.length, "Operations must be unique")
35
35
  .readonly());
36
+ /**
37
+ * Stands in for the fingerprint of an operation approved before fingerprints
38
+ * existed. The storage migration writes it; the first snapshot that carries the
39
+ * operation by name replaces it with the declared fingerprint (`carryGrant`).
40
+ */
41
+ export const unstampedFingerprint = "unstamped";
42
+ /** Operation name to the fingerprint of the data defining what it does. */
43
+ const fingerprintsSchema = z.lazy(() => z.record(z.string().min(1), z.string().min(1)).readonly());
36
44
  /**
37
45
  * Consent approves capabilities, with explicit operation and resource ceilings.
38
46
  * A Release adding a method that requires an already-approved capability needs
39
47
  * no new consent; a new capability does. Release selection intersects stored
40
- * operations instead of adding approvals. Each Worker call is still restricted
48
+ * operations instead of adding approvals: an operation carries only when its
49
+ * name and its fingerprint (the host descriptor method entry, or the binding
50
+ * operation, that defines what it does) both match the approval, so a
51
+ * same-named operation whose behavior changed needs approval again, as a new
52
+ * operation does. Each Worker call is still restricted
41
53
  * to that method's declared requires, never the App's complete capability set.
42
54
  * Only an approved install or change-grants command mints capabilityApproved.
43
55
  * Empty operation rows retain that consent; removing the capability revokes it.
@@ -50,6 +62,8 @@ export const approvedGrantSchema = z
50
62
  capability: ownerCodec(appCapabilityIdSchema),
51
63
  capabilityApproved: z.literal(true),
52
64
  operations: operationsSchema,
65
+ /** Fingerprint of each approved operation as declared when the owner approved it. */
66
+ fingerprints: fingerprintsSchema,
53
67
  resources: z.union([
54
68
  z.literal("tenant-scope"),
55
69
  z.array(resourceRefSchema).readonly(),
@@ -60,6 +74,11 @@ export const approvedGrantSchema = z
60
74
  const approvedGrantsSchema = z.lazy(() => z
61
75
  .array(approvedGrantSchema)
62
76
  .refine((grants) => new Set(grants.map((grant) => grant.capability)).size === grants.length, "Capabilities must be unique")
77
+ .refine((grants) => grants.every((grant) => {
78
+ const names = Object.keys(grant.fingerprints);
79
+ return (names.length === grant.operations.length &&
80
+ grant.operations.every((operation) => names.includes(operation)));
81
+ }), "Every approved operation needs exactly one fingerprint")
63
82
  .readonly());
64
83
  /** A bounded owner edit. Unnamed approvals are not part of the command. */
65
84
  export const grantChangeSchema = z
@@ -67,7 +86,11 @@ export const grantChangeSchema = z
67
86
  capability: ownerCodec(appCapabilityIdSchema),
68
87
  grant: approvedGrantSchema
69
88
  .unwrap()
70
- .omit({ capabilityApproved: true, capability: true })
89
+ .omit({
90
+ capabilityApproved: true,
91
+ capability: true,
92
+ fingerprints: true,
93
+ })
71
94
  .readonly()
72
95
  .nullable(),
73
96
  })
@@ -103,6 +126,34 @@ export const grantCommandSchema = z.discriminatedUnion("kind", [
103
126
  z.strictObject({ kind: z.literal("select-release") }),
104
127
  z.strictObject({ kind: z.literal("delete") }),
105
128
  ]);
129
+ const declaredRow = (declared, capability) => declared.capabilities.find((row) => row.capability === capability);
130
+ /** Fingerprints the declaration currently assigns to these operations. */
131
+ function fingerprintsOf(declared, capability, operations) {
132
+ const row = declaredRow(declared, capability);
133
+ return Object.fromEntries(operations.flatMap((operation) => {
134
+ const fingerprint = row?.operations.includes(operation)
135
+ ? row.fingerprints[operation]
136
+ : undefined;
137
+ return fingerprint === undefined ? [] : [[operation, fingerprint]];
138
+ }));
139
+ }
140
+ /**
141
+ * The part of a stored approval the current declaration still covers: an
142
+ * operation carries only when it is declared and its stored fingerprint equals
143
+ * the declared one (or it was approved before fingerprints existed and is
144
+ * stamped now). Everything else needs the owner's approval again.
145
+ */
146
+ export function carryGrant(grant, declared) {
147
+ const current = fingerprintsOf(declared, grant.capability, grant.operations);
148
+ const operations = grant.operations.filter((operation) => current[operation] !== undefined &&
149
+ (grant.fingerprints[operation] === unstampedFingerprint ||
150
+ current[operation] === grant.fingerprints[operation]));
151
+ return {
152
+ ...grant,
153
+ operations,
154
+ fingerprints: fingerprintsOf(declared, grant.capability, operations),
155
+ };
156
+ }
106
157
  /** One host-independent approval policy; selection only intersects existing grants. */
107
158
  export function applyGrantCommand(current, rawCommand, context) {
108
159
  const refuse = (code) => Result.fail({ kind: "refused", code });
@@ -134,6 +185,7 @@ export function applyGrantCommand(current, rawCommand, context) {
134
185
  capability,
135
186
  capabilityApproved: true,
136
187
  operations: declared(capability),
188
+ fingerprints: fingerprintsOf(context.declaredOperations, capability, declared(capability)),
137
189
  resources: "tenant-scope",
138
190
  }))
139
191
  : [];
@@ -154,24 +206,25 @@ export function applyGrantCommand(current, rawCommand, context) {
154
206
  grants = [
155
207
  ...grants
156
208
  .filter((grant) => !changed.has(grant.capability))
157
- .map((grant) => ({
158
- ...grant,
159
- operations: grant.operations.filter((operation) => declared(grant.capability).includes(operation)),
160
- })),
209
+ .map((grant) => carryGrant(grant, context.declaredOperations)),
161
210
  ...command.changes.flatMap(({ capability, grant }) => grant === null ||
162
211
  (grant.resources !== "tenant-scope" && grant.resources.length === 0)
163
212
  ? []
164
- : [{ capability, ...grant, capabilityApproved: true }]),
213
+ : [
214
+ {
215
+ capability,
216
+ ...grant,
217
+ fingerprints: fingerprintsOf(context.declaredOperations, capability, grant.operations),
218
+ capabilityApproved: true,
219
+ },
220
+ ]),
165
221
  ];
166
222
  break;
167
223
  }
168
224
  case "select-release":
169
225
  grants = grants
170
226
  .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
- }));
227
+ .map((grant) => carryGrant(grant, context.declaredOperations));
175
228
  break;
176
229
  case "delete":
177
230
  grants = [];
@@ -202,6 +255,8 @@ export const declaredOperationsSchema = z.lazy(() => z.strictObject({
202
255
  .strictObject({
203
256
  capability: ownerCodec(appCapabilityIdSchema),
204
257
  operations: operationsSchema,
258
+ /** What each operation does, from its host descriptor method or binding operation. */
259
+ fingerprints: fingerprintsSchema,
205
260
  })
206
261
  .readonly())
207
262
  .readonly(),
@@ -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")