@fungi.computer/oyster 0.47.4 → 0.48.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 (41) hide show
  1. package/README.md +8 -0
  2. package/dist/apps/index.d.ts +1 -0
  3. package/dist/apps/index.js +1 -0
  4. package/dist/apps/install-confirmation.d.ts +26 -0
  5. package/dist/apps/install-confirmation.js +28 -0
  6. package/dist/apps/installation.d.ts +6 -0
  7. package/dist/apps/installation.js +12 -7
  8. package/dist/boot-host-script.js +1 -1
  9. package/dist/build/job-log.d.ts +2 -0
  10. package/dist/build/job-log.js +16 -1
  11. package/dist/cloudflare.d.ts +11 -1
  12. package/dist/cloudflare.js +5 -4
  13. package/dist/embed-metafiles.js +2 -2
  14. package/dist/embed-scripts.js +1 -1
  15. package/dist/frame-failure.d.ts +47 -0
  16. package/dist/frame-failure.js +75 -0
  17. package/dist/hello-app-script.js +1 -1
  18. package/dist/host.d.ts +5 -1
  19. package/dist/host.js +61 -15
  20. package/dist/install-release-cli.d.ts +1 -1
  21. package/dist/install-release-cli.js +73 -24
  22. package/dist/pack.d.ts +52 -1
  23. package/dist/pack.js +54 -11
  24. package/dist/page/app-permissions.js +2 -5
  25. package/dist/page/mount.js +2 -5
  26. package/dist/page-script.js +2 -2
  27. package/dist/standalone/agents.d.ts +1 -1
  28. package/dist/standalone/agents.js +1 -4
  29. package/dist/standalone/computer.d.ts +10 -0
  30. package/dist/standalone/computer.js +43 -1
  31. package/dist/starter-agent.d.ts +1 -3
  32. package/dist/starter-agent.js +4 -8
  33. package/dist/workers.d.ts +4 -0
  34. package/dist/workers.js +28 -1
  35. package/docs/api/apps.md +53 -0
  36. package/docs/api/cloudflare.md +151 -4
  37. package/docs/api/host.md +2 -0
  38. package/docs/api/pack.md +131 -3
  39. package/docs/api/workers-git.md +1 -1
  40. package/docs/api/workers.md +13 -0
  41. package/package.json +12 -12
package/README.md CHANGED
@@ -275,6 +275,10 @@ Install an App Release that `packRelease` produced with the `oyster` command:
275
275
  oyster install ./notes-release --installation-id notes
276
276
  ```
277
277
 
278
+ It lists what the App asks for and asks you to confirm once. Several Releases
279
+ may be given, and then one list covers them all. Add `--yes` to confirm without
280
+ asking; a run with no terminal and no `--yes` installs nothing.
281
+
278
282
  When you need more, add one layer at a time:
279
283
 
280
284
  - `@fungi.computer/oyster/workers-git`: `oysterGitRoot` adds the git door, keys,
@@ -310,6 +314,10 @@ owner-only: a browser signs in only with the owner key, and named keys sign in
310
314
  only by header, for MCP, git and the API. The same Worker runs on Cloudflare
311
315
  Workers and on celld, a Workers-compatible runtime you can host yourself.
312
316
 
317
+ `oyster/apps` decides every App permission, on a standalone Oyster and on Hub
318
+ alike. Each host stores the result: Hub in its Team's App owner, a standalone
319
+ Oyster in its installation store.
320
+
313
321
  Hosts that run teams on this installation model let an owner or an admin approve
314
322
  an App's permissions; a member can install but not approve, and the refusal is
315
323
  `not_approver`. Standalone Oyster has only the owner, so it behaves as before.
@@ -4,4 +4,5 @@ export { permissionPinsSchema, permissionSaveSchema, type PermissionPins, appPer
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";
6
6
  export { appToolPolicySchema, type AppToolAccess, type AppToolEntry, type AppToolPolicy, } from "./tools.js";
7
+ export { installConfirmation, type InstallConfirmation, type InstallConfirmationLine, } from "./install-confirmation.js";
7
8
  export { permissionCatalog, type PermissionCatalogEntry } from "./catalog.js";
@@ -4,4 +4,5 @@ export { permissionPinsSchema, permissionSaveSchema, appPermissionsWireSchema, a
4
4
  export { admits, admitMethodMetadata, appInvocationCeiling, approvedBindingGrants, scopedBindings, grantsFor, gateRefusalSchema, gateRequestSchema, invocationGrantsSchema, } from "./gate.js";
5
5
  export { deriveDeclaredOperations, appCallOperation } from "./operations.js";
6
6
  export { appToolPolicySchema, } from "./tools.js";
7
+ export { installConfirmation, } from "./install-confirmation.js";
7
8
  export { permissionCatalog } from "./catalog.js";
@@ -0,0 +1,26 @@
1
+ import type { AppCapabilityId } from "@fungi.computer/puffball/app";
2
+ import type { TeamRole } from "@fungi.computer/cairn/team-role";
3
+ /** One declared permission as the install confirmation words it. */
4
+ export type InstallConfirmationLine = Readonly<{
5
+ capability: AppCapabilityId;
6
+ label: string;
7
+ description: string;
8
+ warning: string | null;
9
+ /** The Apps in this install that declare it. */
10
+ apps: readonly string[];
11
+ }>;
12
+ /**
13
+ * Every permission an install declares, once, for one confirmation. `granted`
14
+ * is what confirming approves; `needsApproval` is what stays refused until an
15
+ * owner approves it. Both come from the rule the install reducer applies, so
16
+ * the list cannot promise more or less than the install does.
17
+ */
18
+ export type InstallConfirmation = Readonly<{
19
+ granted: readonly InstallConfirmationLine[];
20
+ needsApproval: readonly InstallConfirmationLine[];
21
+ }>;
22
+ /** Merge any number of Apps into one combined, once-per-permission list. */
23
+ export declare function installConfirmation(role: TeamRole | null, apps: readonly Readonly<{
24
+ name: string;
25
+ capabilities: readonly AppCapabilityId[];
26
+ }>[]): InstallConfirmation;
@@ -0,0 +1,28 @@
1
+ import { permissionCatalog } from "./catalog.js";
2
+ import { installApprovedCapabilities } from "./installation.js";
3
+ /** Merge any number of Apps into one combined, once-per-permission list. */
4
+ export function installConfirmation(role, apps) {
5
+ const granted = new Map();
6
+ const waiting = new Map();
7
+ for (const { name, capabilities } of apps) {
8
+ const approved = new Set(installApprovedCapabilities(role, capabilities));
9
+ for (const capability of capabilities) {
10
+ // Affordances grant nothing and need no consent, so they are not listed.
11
+ if (permissionCatalog[capability].consent === "affordance")
12
+ continue;
13
+ const into = approved.has(capability) ? granted : waiting;
14
+ into.set(capability, [...(into.get(capability) ?? []), name]);
15
+ }
16
+ }
17
+ const lines = (rows) => [...rows].map(([capability, names]) => {
18
+ const entry = permissionCatalog[capability];
19
+ return {
20
+ capability,
21
+ label: entry.label,
22
+ description: entry.description,
23
+ warning: entry.warning,
24
+ apps: [...new Set(names)],
25
+ };
26
+ });
27
+ return { granted: lines(granted), needsApproval: lines(waiting) };
28
+ }
@@ -130,6 +130,12 @@ export type GrantRefusal = Readonly<{
130
130
  kind: "refused";
131
131
  code: "stale_authority" | "not_approver" | "not_declared" | "invalid_command";
132
132
  }>;
133
+ /**
134
+ * What an install approves, for the reducer and for the confirmation shown
135
+ * before it. An approver's install approves the install-class set; a member's
136
+ * approves only the App's own storage, so every other capability waits.
137
+ */
138
+ export declare function installApprovedCapabilities<Capability extends ApprovedGrant["capability"]>(role: TeamRole | null, capabilities: readonly Capability[], builtInShell?: boolean): Capability[];
133
139
  /**
134
140
  * The part of a stored approval the current declaration still covers: an
135
141
  * operation carries only when it is declared and its stored fingerprint equals
@@ -129,6 +129,17 @@ export const grantCommandSchema = z.discriminatedUnion("kind", [
129
129
  ]);
130
130
  /** Owners and admins approve App permissions; members manage installs only. */
131
131
  const approves = (role) => role !== null && teamRoleAtLeast(role, "admin");
132
+ /**
133
+ * What an install approves, for the reducer and for the confirmation shown
134
+ * before it. An approver's install approves the install-class set; a member's
135
+ * approves only the App's own storage, so every other capability waits.
136
+ */
137
+ export function installApprovedCapabilities(role, capabilities, builtInShell = false) {
138
+ return capabilities.filter((capability) => capability === "app.storage" ||
139
+ (approves(role) &&
140
+ (permissionCatalog[capability].consent === "install" ||
141
+ (capability === "team.workbenchHost" && builtInShell))));
142
+ }
132
143
  const declaredRow = (declared, capability) => declared.capabilities.find((row) => row.capability === capability);
133
144
  /** Fingerprints the declaration currently assigns to these operations. */
134
145
  function fingerprintsOf(declared, capability, operations) {
@@ -181,13 +192,7 @@ export function applyGrantCommand(current, rawCommand, context) {
181
192
  // An approver's install approves the install-class set. A member's
182
193
  // install approves only the App's own storage, which touches nothing
183
194
  // beyond the App's own data; every other capability waits for an approver.
184
- grants = context.declaration.capabilities
185
- .filter((capability) => capability === "app.storage" ||
186
- (approves(context.principal.role) &&
187
- (permissionCatalog[capability].consent === "install" ||
188
- (capability === "team.workbenchHost" &&
189
- context.builtInShell === true))))
190
- .map((capability) => ({
195
+ grants = installApprovedCapabilities(context.principal.role, context.declaration.capabilities, context.builtInShell === true).map((capability) => ({
191
196
  capability,
192
197
  capabilityApproved: true,
193
198
  operations: declared(capability),