@anchrd/intel-contract 0.19.0 → 0.20.0

package/README.md

@@ -95,10 +95,15 @@ edge and the tool ends up in the chain. The graph is then refused with
 `Node <id> is a link and must be attached to a step` — in `title`, per the first item above. A step
 may hold several links; one link belongs to exactly one step.
 
-### A flow is not a node, and carries no grants of its own
+### A flow is not a node, and has its own grant calls
 
-`node_grant_create` addresses nodes. A flow has no grants; it inherits those of the folder it lives
-in. To change who reaches a flow, share its folder — or move the flow.
+`node_grant_create` addresses nodes; `flow_grant_create` addresses flows. A flow is reached by both:
+the folder it is filed in passes its grants down, and a grant may sit on the flow itself. The two
+add up — the flow grant never replaces what the folder passes down.
+
+⚠️ A grant on one flow reaches **that flow** and nothing else — not the folder, and not the flows it
+calls. `ShareResult` says so: `unrunnable` names the sub-flows the new principal could not start,
+by title where you may see them and by count where you may not.
 
 ### Import takes its idempotency key as a header
 

package/dist/contract/flow.js

@@ -438,9 +438,9 @@ export const FlowPublishPreview = z.strictObject({
     calls: z.array(FlowPublishCall),
     tools: z.array(FlowPublishTool),
 });
-// A flow has no share schema of its own. A grant sits on the folder a flow is filed in and inherits
-// down from there (ADR-0004 §2); a narrower grant beside it would destroy the subtree guarantee
-// section 3 rests on, so per-flow grants were removed rather than deprecated.
+// A flow's own sharing schemas live in `share.ts` beside the node's (#530): `ShareFlowInput`,
+// `RevokeFlowGrantInput`, `ListFlowGrantsInput`. They are there rather than here because a grant is
+// one subject with two kinds of target, not two features — and `ShareResult` answers for both.
 // What accesses what, for one level of the shared tree (#19). A folder answers it for its contents,
 // a single flow for itself. Documents and flows are two kinds of thing that share one tree
 // (ADR-0004 §1), so the graph carries both and says which of them it is.

package/dist/contract/share.d.ts

@@ -20,6 +20,10 @@ export declare const ListGrantsInput: z.ZodObject<{
     resourceId: z.ZodString;
 }, z.core.$strict>;
 export type ListGrantsInput = z.infer<typeof ListGrantsInput>;
+export declare const ListFlowGrantsInput: z.ZodObject<{
+    flowId: z.ZodString;
+}, z.core.$strict>;
+export type ListFlowGrantsInput = z.infer<typeof ListFlowGrantsInput>;
 export declare const ResourceGrant: z.ZodObject<{
     id: z.ZodString;
     resourceId: z.ZodString;
@@ -70,6 +74,33 @@ export declare const RevokeGrantInput: z.ZodObject<{
     idempotencyKey: z.ZodString;
 }, z.core.$strict>;
 export type RevokeGrantInput = z.infer<typeof RevokeGrantInput>;
+export declare const ShareFlowInput: z.ZodObject<{
+    flowId: z.ZodString;
+    principal: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"user">;
+        id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"email">;
+        email: z.ZodEmail;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"organization">;
+    }, z.core.$strict>], "type">;
+    verb: z.ZodEnum<{
+        read: "read";
+        write: "write";
+        execute: "execute";
+        share: "share";
+    }>;
+    expiresAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type ShareFlowInput = z.infer<typeof ShareFlowInput>;
+export declare const RevokeFlowGrantInput: z.ZodObject<{
+    flowId: z.ZodString;
+    grantId: z.ZodString;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type RevokeFlowGrantInput = z.infer<typeof RevokeFlowGrantInput>;
 export declare const UnreadableNodes: z.ZodObject<{
     titles: z.ZodArray<z.ZodString>;
     hidden: z.ZodNumber;
@@ -102,6 +133,10 @@ export declare const ShareResult: z.ZodObject<{
         titles: z.ZodArray<z.ZodString>;
         hidden: z.ZodNumber;
     }, z.core.$strict>;
+    unrunnable: z.ZodDefault<z.ZodObject<{
+        titles: z.ZodArray<z.ZodString>;
+        hidden: z.ZodNumber;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ShareResult = z.infer<typeof ShareResult>;
 export declare const ResourceGrantList: z.ZodObject<{

package/dist/contract/share.js

@@ -17,6 +17,12 @@ export const SharePrincipal = z.discriminatedUnion("type", [
 export const ListGrantsInput = z.strictObject({
     resourceId: IntelId.describe("Node whose direct grants to list. Access inherited from a folder above is not a grant on this node and is not listed here."),
 });
+// The same three shapes for a flow (#530). Separate inputs rather than a widened `resourceId`,
+// because the id names a different table and a caller that passes the wrong kind should be told so
+// by the route it called rather than by a lookup that finds nothing.
+export const ListFlowGrantsInput = z.strictObject({
+    flowId: IntelId.describe("Flow whose direct grants to list. Access inherited from the folder it is filed in is not a grant on this flow and is not listed here."),
+});
 export const ResourceGrant = z.strictObject({
     id: IntelId,
     resourceId: IntelId,
@@ -40,6 +46,20 @@ export const RevokeGrantInput = z.strictObject({
     grantId: IntelId.describe("The grant to withdraw, from node_grant_list."),
     idempotencyKey: IdempotencyKey,
 });
+export const ShareFlowInput = z.strictObject({
+    flowId: IntelId.describe("Flow to grant access to. A grant here reaches this flow and nothing else — not the folder it is filed in, and not the flows it calls."),
+    principal: SharePrincipal.describe("Who gets the access: a Gate user by id, someone by verified email address, or the whole organization."),
+    verb: ResourceVerb.describe("What they may do. Each verb is granted on its own and none implies another: `read` opens the flow, `write` edits it, `execute` runs it, `share` passes access on."),
+    expiresAt: IsoDateTime.nullable()
+        .default(null)
+        .describe("When the grant stops working, or `null` for one that does not expire on its own."),
+    idempotencyKey: IdempotencyKey,
+});
+export const RevokeFlowGrantInput = z.strictObject({
+    flowId: IntelId.describe("Flow the grant sits on. Named alongside the grant id so access is decided on the flow."),
+    grantId: IntelId.describe("The grant to withdraw, from flow_grant_list."),
+    idempotencyKey: IdempotencyKey,
+});
 // What a grant does not cover, reported to whoever just made it. A flow in the shared folder may
 // read a document outside it, and the run is re-authorized against the person running it — so the
 // grant can be complete and the flow still stop for them (ADR-0004 §4).
@@ -53,9 +73,17 @@ export const UnreadableNodes = z.strictObject({
 // The grant is in the answer, so the warning cannot be mistaken for a refusal: it is written first
 // and described afterwards. Blocking would force everyone who uses a central policy document to
 // duplicate it, which is the opposite of what one tree is for (ADR-0004 §4).
+//
+// ⚠️ `unrunnable` is the second half of the same sentence and belongs to the flow grant (#530). A
+// grant on a folder covered every flow beneath it, so there was nothing to say; a grant on one flow
+// reaches that flow and stops, and the sub-flows it calls are then somebody else's to grant. It
+// carries the shape of `UnreadableNodes` because it answers the same question — what this grant
+// does NOT reach, named where the sharer may see it and counted where they may not — and it is
+// empty for every node grant.
 export const ShareResult = z.strictObject({
     grant: ResourceGrant,
     unreadable: UnreadableNodes,
+    unrunnable: UnreadableNodes.default({ titles: [], hidden: 0 }),
 });
 // `applicableVerbs` travels with the list because the answer is the business layer's, not the
 // screen's: a document has nothing to execute, so `execute` is not offered on one (ADR-0004 §2).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {