@fungi.computer/oyster 0.28.2 → 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.
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<{
@@ -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";
@@ -127,7 +128,7 @@ export type GrantContext = Readonly<{
127
128
  }>;
128
129
  export type GrantRefusal = Readonly<{
129
130
  kind: "refused";
130
- code: "stale_authority" | "not_owner" | "not_declared" | "invalid_command";
131
+ code: "stale_authority" | "not_approver" | "not_declared" | "invalid_command";
131
132
  }>;
132
133
  /**
133
134
  * The part of a stored approval the current declaration still covers: an
@@ -273,7 +274,7 @@ export type InstallationCommand = z.output<typeof installationCommandSchema>;
273
274
  /** Values captured by the host; identities and time are never generated by the reducer. */
274
275
  export type InstallationContext = Readonly<{
275
276
  by: HostActor;
276
- role: "owner" | "member" | null;
277
+ role: TeamRole | null;
277
278
  expectedVersion: number | null;
278
279
  declaration: AppDeclaration;
279
280
  declaredOperations: DeclaredOperations;
@@ -290,7 +291,7 @@ export declare const installationRefusalSchema: z.ZodLazy<z.ZodObject<{
290
291
  stale_authority: "stale_authority";
291
292
  not_declared: "not_declared";
292
293
  release_app_mismatch: "release_app_mismatch";
293
- not_owner: "not_owner";
294
+ not_approver: "not_approver";
294
295
  invalid_command: "invalid_command";
295
296
  }>;
296
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";
@@ -126,6 +127,8 @@ export const grantCommandSchema = z.discriminatedUnion("kind", [
126
127
  z.strictObject({ kind: z.literal("select-release") }),
127
128
  z.strictObject({ kind: z.literal("delete") }),
128
129
  ]);
130
+ /** Owners and admins approve App permissions; members manage installs only. */
131
+ const approves = (role) => role !== null && teamRoleAtLeast(role, "admin");
129
132
  const declaredRow = (declared, capability) => declared.capabilities.find((row) => row.capability === capability);
130
133
  /** Fingerprints the declaration currently assigns to these operations. */
131
134
  function fingerprintsOf(declared, capability, operations) {
@@ -167,28 +170,27 @@ export function applyGrantCommand(current, rawCommand, context) {
167
170
  if ((context.expectedVersion ?? 0) !== (current?.authorityVersion ?? 0))
168
171
  return refuse("stale_authority");
169
172
  if (context.principal.role === null ||
170
- (command.kind === "change-grants" && context.principal.role !== "owner"))
171
- return refuse("not_owner");
173
+ (command.kind === "change-grants" && !approves(context.principal.role)))
174
+ return refuse("not_approver");
172
175
  const declared = (capability) => context.declaredOperations.capabilities.find((row) => row.capability === capability)?.operations ?? [];
173
176
  const version = (current?.authorityVersion ?? 0) + 1;
174
177
  let grants = current?.approvedGrants ?? [];
175
178
  let approval = current?.approval ?? null;
176
179
  switch (command.kind) {
177
180
  case "install":
178
- grants =
179
- context.principal.role === "owner"
180
- ? context.declaration.capabilities
181
- .filter((capability) => permissionCatalog[capability].consent === "install" ||
182
- (capability === "team.workbenchHost" &&
183
- context.builtInShell === true))
184
- .map((capability) => ({
185
- capability,
186
- capabilityApproved: true,
187
- operations: declared(capability),
188
- fingerprints: fingerprintsOf(context.declaredOperations, capability, declared(capability)),
189
- resources: "tenant-scope",
190
- }))
191
- : [];
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
+ : [];
192
194
  break;
193
195
  case "change-grants": {
194
196
  for (const { capability, grant } of command.changes) {
@@ -299,7 +301,7 @@ export const installationRefusalSchema = z.lazy(() => z.strictObject({
299
301
  code: z.enum([
300
302
  "unavailable",
301
303
  "stale_authority",
302
- "not_owner",
304
+ "not_approver",
303
305
  "not_declared",
304
306
  "release_app_mismatch",
305
307
  "invalid_command",
@@ -324,8 +326,8 @@ export function applyInstallationCommand(current, rawCommand, context) {
324
326
  context.expectedVersion !== current.authority.authorityVersion) {
325
327
  return refuse("stale_authority");
326
328
  }
327
- if (command.kind === "change-grants" && context.role !== "owner")
328
- return refuse("not_owner");
329
+ if (command.kind === "change-grants" && !approves(context.role))
330
+ return refuse("not_approver");
329
331
  const release = command.kind === "install" || command.kind === "select-release"
330
332
  ? command.release
331
333
  : current?.release;
@@ -1,3 +1,4 @@
1
+ import type { TeamRole } from "@fungi.computer/cairn/team-role";
1
2
  /**
2
3
  * Oyster's one authorization owner. Every Oyster HTTP route is registered
3
4
  * through {@link routes} with a typed {@link Requirement}; a table's `serve`
@@ -46,7 +47,7 @@ export type OwnerPrincipal = Readonly<{
46
47
  export declare function oysterPrincipalIsOwner(principal: TenantPrincipal): principal is OwnerPrincipal;
47
48
  /** A member, owner or not, as member routes receive it. */
48
49
  export type MemberPrincipal = Extract<TenantPrincipal, {
49
- role: "owner" | "member";
50
+ role: TeamRole;
50
51
  }>;
51
52
  /** The live facts this module reads to decide; every host supplies the same ports. */
52
53
  export type AuthorityPorts = Readonly<{