authority: ship the module's package, the hop's Version declares its policy, the hop declares authority 0.3.3

.github/workflows/go.yml

@@ -4,6 +4,10 @@ name: go
 # request and on main. tools/noproxygate's test is the no-proxy gate: it
 # type-checks every module and refuses requests, dials and subprocesses that
 # bypass host.HTTPTransport and host.DialOptions.
+# tools/packagegate's test is the package gate: every module a run admits
+# ships its package manifest, and its contracts match what `codefly generate
+# contracts` writes from the services' sources, and every method a host
+# fronting the module receives declares its policy.
 
 on:
   pull_request:

README.md

@@ -1042,7 +1042,9 @@ the key again at the next renewal, a restarted hop re-registers the same entry,
 and a key no running hop signs with is withdrawn without being named. The seed
 never leaves the hop; nothing about the hop is configured on the authority. It
 is additive too. The local authority implements it; `accounts` implementing the
-same registration is follow-up work in the host.
+same registration is follow-up work in the host. The hop calls it, so the hop
+requires `>=0.3.3 <0.4.0`: a host below 0.3.3 is refused at render instead of
+leaving every module's verifier to refuse every call.
 
 The 0.3.1 authority version is an additive pre-stable revision selected for
 this refresh so existing `>=0.2.0 <0.4.0` consumers admit it. It retains 0.3.0's

modules/authority/contracts.codefly.yaml

@@ -0,0 +1,8 @@
+# Publication configuration for `codefly generate contracts`: the local
+# authority's grpc listener serves its own LocalService and the host interfaces
+# (authority, composition, installation, session) plus the artifact service, so
+# the catalog carries what that listener serves. The hop's endpoints serve one
+# package each and need no inventory.
+schema: codefly/module-contracts-config/v1
+surfaces:
+    local: contract-surfaces.json

modules/authority/contracts/api/catalog.codefly.json

@@ -0,0 +1,135 @@
+{
+  "schema": "codefly/module-api-contracts/v1",
+  "package": "codefly/authority",
+  "version": "0.1.0",
+  "endpoints": [
+    {
+      "service": "hop",
+      "endpoint": "grpc",
+      "api": "grpc",
+      "kind": "protobuf",
+      "package": "api",
+      "path": "contracts/api/hop/grpc/contract.binpb",
+      "digest": "sha256:a85d37ee2ac63dcaa92f00ce43e9d7ca180d3f76006739b47716b5dcd1b1f8e2",
+      "services": [
+        {
+          "name": "HopService",
+          "fullName": "api.HopService",
+          "procedures": [
+            "/api.HopService/Version"
+          ]
+        }
+      ]
+    },
+    {
+      "service": "hop",
+      "endpoint": "http",
+      "api": "http",
+      "kind": "openapi",
+      "package": "api.proto",
+      "path": "contracts/api/hop/http/openapi.json",
+      "digest": "sha256:8907423351d7c8d1970bab6e2edbe0905b3c613dbfebbfad628f87f28701dfef",
+      "routes": [
+        {
+          "method": "GET",
+          "path": "/version"
+        }
+      ]
+    },
+    {
+      "service": "local",
+      "endpoint": "grpc",
+      "api": "grpc",
+      "kind": "protobuf",
+      "package": "",
+      "path": "contracts/api/local/grpc/contract.binpb",
+      "digest": "sha256:1c51ec903d141b1df6c0eff0fcaa10aa48b6633e0753a13718bef83d086dc0cb",
+      "services": [
+        {
+          "name": "LocalService",
+          "fullName": "api.LocalService",
+          "procedures": [
+            "/api.LocalService/Version"
+          ]
+        },
+        {
+          "name": "ArtifactService",
+          "fullName": "host.artifact.v1.ArtifactService",
+          "procedures": [
+            "/host.artifact.v1.ArtifactService/Approve",
+            "/host.artifact.v1.ArtifactService/Authorize",
+            "/host.artifact.v1.ArtifactService/Revoke"
+          ]
+        },
+        {
+          "name": "AuthorityService",
+          "fullName": "host.authority.v1.AuthorityService",
+          "procedures": [
+            "/host.authority.v1.AuthorityService/AttachResource",
+            "/host.authority.v1.AuthorityService/AuthorizeTransfer",
+            "/host.authority.v1.AuthorityService/Check",
+            "/host.authority.v1.AuthorityService/Delegate",
+            "/host.authority.v1.AuthorityService/DetachResource",
+            "/host.authority.v1.AuthorityService/GetDelegation",
+            "/host.authority.v1.AuthorityService/Issue",
+            "/host.authority.v1.AuthorityService/Keys",
+            "/host.authority.v1.AuthorityService/ListResources",
+            "/host.authority.v1.AuthorityService/RegisterAdmissionKey",
+            "/host.authority.v1.AuthorityService/RevokeDelegation"
+          ]
+        },
+        {
+          "name": "CompositionService",
+          "fullName": "host.composition.v1.CompositionService",
+          "procedures": [
+            "/host.composition.v1.CompositionService/ApplyManifest"
+          ]
+        },
+        {
+          "name": "InstallationService",
+          "fullName": "host.installation.v1.InstallationService",
+          "procedures": [
+            "/host.installation.v1.InstallationService/GrantRole",
+            "/host.installation.v1.InstallationService/Install",
+            "/host.installation.v1.InstallationService/List",
+            "/host.installation.v1.InstallationService/ListRoleGrants",
+            "/host.installation.v1.InstallationService/Review",
+            "/host.installation.v1.InstallationService/RevokeRole"
+          ]
+        },
+        {
+          "name": "OfferService",
+          "fullName": "host.installation.v1.OfferService",
+          "procedures": [
+            "/host.installation.v1.OfferService/ListOffers",
+            "/host.installation.v1.OfferService/ReviewOffer"
+          ]
+        },
+        {
+          "name": "SessionService",
+          "fullName": "host.session.v1.SessionService",
+          "procedures": [
+            "/host.session.v1.SessionService/Current",
+            "/host.session.v1.SessionService/ListFixturePeople",
+            "/host.session.v1.SessionService/SignIn"
+          ]
+        }
+      ]
+    },
+    {
+      "service": "local",
+      "endpoint": "rest",
+      "api": "rest",
+      "kind": "openapi",
+      "package": "api.proto",
+      "path": "contracts/api/local/rest/openapi.json",
+      "digest": "sha256:dc9c7adab86fcf9878f145988c5a5eddf509ac9f59980f0f660b804c91258796",
+      "routes": [
+        {
+          "method": "GET",
+          "path": "/version"
+        }
+      ]
+    }
+  ]
+}

modules/authority/contracts/api/hop/grpc/proto/api.proto

@@ -0,0 +1,27 @@
+syntax = "proto3";
+package api;
+
+// Keep the Go import path stable while the protobuf package remains free to
+// evolve into a versioned wire namespace (for example coordination.v1).
+option go_package = "hop/pkg/gen;gen";
+
+import "authority/hop/v1/policy.proto";
+import "google/api/annotations.proto";
+
+message VersionRequest {
+}
+
+message VersionResponse {
+    string version = 1;
+}
+
+service HopService {
+    // Version is the hop's own method. A caller the authority checked may read
+    // it; the hop serves it without a scope, as the console serves its Version.
+    rpc Version(VersionRequest) returns (VersionResponse) {
+        option (authority.hop.v1.policy) = {any_checked_caller: true};
+        option (google.api.http) = {
+            get: "/version"
+        };
+    }
+}

modules/authority/contracts/api/hop/grpc/proto/authority/VENDORED.md

@@ -0,0 +1,11 @@
+# Vendored: the authority's method policy
+
+`hop/v1/policy.proto` is a byte-for-byte copy of
+`libraries/hop/proto/authority/hop/v1/policy.proto` in this repository, so the
+hop's proto can mark its own methods with the option.
+
+This is a stopgap. No Codefly library exports a proto yet, so a module cannot
+import another's option through the CLI, and every module in the fleet copies
+the option protos it uses by hand. The real fix, codefly-dev/cli#1130, is the
+CLI importing a proto a library exports. Until then `code/vendored_test.go`
+fails when this copy drifts from its source.

modules/authority/contracts/api/hop/grpc/proto/authority/hop/v1/policy.proto

@@ -0,0 +1,38 @@
+syntax = "proto3";
+
+// The authority's declaration of what a call to one method must hold. A module
+// marks each method it serves; the hop in front of the module reads the marks
+// and lets a call through only when the authority checked its Work Context and
+// the call holds what its method declares.
+package authority.hop.v1;
+
+import "google/protobuf/descriptor.proto";
+
+option go_package = "github.com/codefly-dev/authority/libraries/hop/go/gen/authority/hop/v1;hopv1";
+
+// Policy is one method's declaration. Exactly one of its two fields is set: a
+// method that requires nothing says so with any_checked_caller, because an
+// absent declaration and "nothing is required" must not look the same. The hop
+// refuses every call to a method that declares neither, or both.
+message Policy {
+  // Requires lists what the call must hold, every entry: each action on its
+  // resource kind, in the call's effective authority.
+  repeated Requirement requires = 1;
+  // AnyCheckedCaller lets through any call whose Work Context the authority
+  // checked, holding nothing in particular.
+  bool any_checked_caller = 2;
+}
+
+// Requirement is actions on one resource kind, spelled in the kind's own
+// vocabulary as the module's contract declares it.
+message Requirement {
+  // ResourceKind is the kind, as the module's scope ceilings name it.
+  string resource_kind = 1;
+  // Actions are each required.
+  repeated string actions = 2;
+}
+
+extend google.protobuf.MethodOptions {
+  // policy is the method's declaration.
+  Policy policy = 51100;
+}

modules/authority/contracts/api/hop/grpc/proto/buf.gen.yaml

@@ -0,0 +1,29 @@
+# The service's own bindings: api.proto alone, named as the one input so the
+# agent's sync and `codefly generate proto` write the same files; the hop's
+# policy option (authority/hop/v1, vendored to compile) is an import whose
+# bindings the hop library publishes.
+#
+# Go package identity is explicit in api.proto. Managed rewriting couples Go
+# package names to protobuf namespaces and breaks versioned wire packages.
+version: v2
+managed:
+  enabled: false
+inputs:
+  - directory: .
+    paths:
+      - api.proto
+plugins:
+  - local: protoc-gen-go
+    out: ../code/pkg/gen
+    opt: paths=source_relative
+  - local: protoc-gen-go-grpc
+    out: ../code/pkg/gen
+    opt: paths=source_relative
+  - local: protoc-gen-grpc-gateway
+    out: ../code/pkg/gen
+    opt: paths=source_relative
+  - local: protoc-gen-connect-go
+    out: ../code/pkg/gen
+    opt: paths=source_relative
+  - local: protoc-gen-openapiv2
+    out: ../openapi

modules/authority/contracts/api/hop/grpc/proto/buf.lock

@@ -0,0 +1,8 @@
+# Generated by buf. DO NOT EDIT.
+version: v1
+deps:
+  - remote: buf.build
+    owner: googleapis
+    repository: googleapis
+    commit: 8ac61b9e502343289c8c42b17aa5b245
+    digest: shake256:30840693e3b5edac0f461e7168da1057b36a5df75d2d0c6fd920f8442a2f51afb22c955ad5afc25a1394f6e2de65d623844594a37d9f9ce093c48d6afe6a3e55

modules/authority/contracts/api/hop/grpc/proto/buf.yaml

@@ -0,0 +1,7 @@
+version: v1
+deps:
+  - buf.build/googleapis/googleapis
+lint:
+  use:
+    - DEFAULT
+    - COMMENTS

modules/authority/contracts/api/hop/http/openapi.json

@@ -0,0 +1,81 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "api.proto",
+    "version": "version not set"
+  },
+  "tags": [
+    {
+      "name": "HopService"
+    }
+  ],
+  "consumes": [
+    "application/json"
+  ],
+  "produces": [
+    "application/json"
+  ],
+  "paths": {
+    "/version": {
+      "get": {
+        "summary": "Version is the hop's own method. A caller the authority checked may read\nit; the hop serves it without a scope, as the console serves its Version.",
+        "operationId": "HopService_Version",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiVersionResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "tags": [
+          "HopService"
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "apiVersionResponse": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string"
+        }
+      }
+    },
+    "protobufAny": {
+      "type": "object",
+      "properties": {
+        "@type": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": {}
+    },
+    "rpcStatus": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int32"
+        },
+        "message": {
+          "type": "string"
+        },
+        "details": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

modules/authority/contracts/api/local/grpc/proto/api.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+package api;
+
+// Keep the Go import path stable while the protobuf package remains free to
+// evolve into a versioned wire namespace (for example coordination.v1).
+option go_package = "gateway/pkg/gen;gen";
+
+import "google/api/annotations.proto";
+
+message VersionRequest {
+}
+
+message VersionResponse {
+    string version = 1;
+}
+
+service LocalService {
+    rpc Version(VersionRequest) returns (VersionResponse) {
+        option (google.api.http) = {
+            get: "/version"
+        };
+    }
+}