api-bones-protos 0.3.0

Embedded bytes of the api-bones canonical proto shapes (bones/v1/*.proto). Pair with `proto-build-kit` to stage on the protoc include path at build time.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

// SPDX-License-Identifier: LicenseRef-Proprietary
//
// Method-level annotations for service authors.
//
// `bones.v1.errors` — declares the error variants an RPC may return.
// Variant names are ALL_CAPS_SNAKE strings referencing the service's
// companion error enum (the enum itself is service-owned; this
// option just enumerates which variants apply per RPC).
//
// Usage:
//
//   service AuthService {
//     rpc Login(LoginRequest) returns (LoginResponse) {
//       option (bones.v1.errors) = "INVALID_CREDENTIALS";
//       option (bones.v1.errors) = "ACCOUNT_LOCKED";
//       option (bones.v1.errors) = "MFA_REQUIRED";
//     }
//   }
//
// SDK generators consume the annotation to emit typed per-RPC error
// surfaces; undeclared runtime errors map to a catch-all variant
// keyed off `google.rpc.Status`.
//
// `bones.v1.authz` — declares which principal class may call an RPC.
// The declaration belongs to the contract, so it travels with the
// contract: the RPC carries it, not the server implementation.
//
// Usage:
//
//   service ReservationService {
//     rpc Reserve(ReserveRequest) returns (ReserveResponse) {
//       option (bones.v1.authz) = { kind: AUTHZ_KIND_SERVICE };
//     }
//     rpc GetHealth(GetHealthRequest) returns (GetHealthResponse) {
//       option (bones.v1.authz) = {
//         kind: AUTHZ_KIND_PUBLIC,
//         reason: "liveness probe, no tenant data"
//       };
//     }
//   }
//
// An RPC with no `authz` option is denied. A new RPC is therefore
// secure before anyone remembers it exists; declaring the class is
// the only way to make it reachable.

syntax = "proto3";

package bones.v1;

import "google/protobuf/descriptor.proto";

extend google.protobuf.MethodOptions {
  // Declared error variants for this RPC. Variant names are
  // ALL_CAPS_SNAKE and must match a value in the service's
  // companion error enum. See file header for full semantics.
  repeated string errors = 5102347;

  // Declared authorization class for this RPC. Absent option means
  // the RPC is denied to every caller. See file header for usage.
  AuthzRule authz = 5102348;
}

// Principal class admitted by an RPC.
enum AuthzKind {
  // No class declared. Enforcement denies the RPC — the option must
  // name a class explicitly for the RPC to be reachable.
  AUTHZ_KIND_UNSPECIFIED = 0;

  // Requires a service principal (SVID-derived workload identity).
  AUTHZ_KIND_SERVICE = 1;

  // Requires a user principal.
  AUTHZ_KIND_USER = 2;

  // Served without authentication. `reason` is mandatory and must be
  // non-empty: an unauthenticated route is a decision that has to be
  // justified in the contract where reviewers can see it.
  AUTHZ_KIND_PUBLIC = 3;
}

// Authorization declaration attached to an RPC.
message AuthzRule {
  // Principal class admitted by the RPC.
  AuthzKind kind = 1;

  // Why the RPC carries this class. Mandatory and non-empty for
  // AUTHZ_KIND_PUBLIC; optional for the authenticated classes.
  string reason = 2;
}