API: Package onboarding (publisher and reviewer trust)

Capability state: every operation in this file is staging-durable. Authority package publisher and reviewer trust roots are recorded in durable M7 state but refuse production admission, reject private key material at the membrane, and stay fixture trust roots that do not enable production package activation. See 022 gap report for the broader package-trust surface.

The package-onboarding cluster covers the Verlag publisher and reviewer trust roots — the staging-durable records that name a publisher (Verlag) and a reviewer who can sign authority package candidates and reviews, with optional public ES256 verification material and no private key ingress.

Two coupled lanes:

• Publisher lane — authority.package.publisher.onboard records a Verlag publisher trust root with optional public verification material, an algorithm, and an optional reliance terms hash.
• Reviewer lane — authority.package.reviewer.onboard records a reviewer trust root tied to a separate standing ref, with a conflict policy hash, optional public verification material, and an explicit reviewer_conflict: false assertion.

These onboarding records are the missing piece before authority.package.candidate, authority.package.review, authority.package.activate, and authority.package.revoke can operate against external trust. See authority.md for the package activation, revocation, and inspection surfaces this onboarding feeds.

Boundary assertions made explicit by the handlers:

• Both onboarding handlers refuse if private_key_material (or raw_reviewer_notes) is supplied at the membrane.
• Public key hashes are validated when uncompressed hex is supplied; mismatches refuse with authority_package_trust_public_key_invalid.
• Reviewer onboarding refuses without a separate standing_ref and refuses if reviewer_conflict is true.

authority.package.publisher.onboard

Record staging Verlag publisher trust root with optional public ES256 verification material and without private key ingress.

POST /v1/authority/packages/publishers/onboard
state: staging-durable
sdk_role: record staging Verlag publisher trust root with optional public ES256 verification material and without private key ingress
request_record: CloudAuthorityPackagePublisherTrustRequest
responses: publisher_trust | public_key_hash | public_verification_material | refusal | receipt

Request

interface PackagePublisherTrustRequest {
  tenant: GestaltRef;
  publisher_ref: GestaltRef;
  trust_ref?: GestaltRef;
  public_key_hash?: string;
  public_key_algorithm: string;          // expected: "ES256"
  public_key_uncompressed_hex?: string;
  reliance_terms_hash?: string;
  fixture: boolean;                       // must be true
  private_key_material?: unknown;         // refused if present
}

Response

{
  "operation": "authority.package.publisher.onboard",
  "outcome": "admitted",
  "body": {
    "publisher_trust": "authority_publisher_trust:...",
    "publisher": "pendulum:fixture_verlag",
    "public_key_hash": "sha256:...",
    "public_verification_material": {
      "public_key_algorithm": "ES256",
      "public_key_hash": "sha256:...",
      "public_key_uncompressed_hex": "...",
      "external_signature_verification_supported": true,
      "private_key_material_exposed": false
    },
    "private_key_material_stored": false,
    "private_key_material_exposed": false,
    "durable_state": {...},
    "production_admission": false
  },
  "receipt": {...}
}

The handler refuses with authority_package_publisher_private_key_refused if private_key_material is supplied, authority_package_publisher_trust_missing if fixture is false, and authority_package_trust_public_key_invalid if the uncompressed hex is not a valid ES256 key or its hash does not match the supplied public_key_hash.

SDK example

const publisher = await client.packagePublisherOnboard({
  tenant: "tenant_node:rheinwerk_calibration",
  publisher_ref: "pendulum:fixture_verlag",
  public_key_hash: "sha256:fixture_verlag_public_key",
  public_key_algorithm: "ES256",
  reliance_terms_hash: "sha256:fixture_reliance_terms",
  fixture: true,
});

authority.package.reviewer.onboard

Record staging reviewer trust root with standing conflict policy and optional public ES256 verification material.

POST /v1/authority/packages/reviewers/onboard
state: staging-durable
sdk_role: record staging reviewer trust root with standing conflict policy and optional public ES256 verification material
request_record: CloudAuthorityPackageReviewerTrustRequest
responses: reviewer_trust | standing | conflict_policy_hash | public_verification_material | refusal | receipt

Request

interface PackageReviewerTrustRequest {
  tenant: GestaltRef;
  reviewer_ref: GestaltRef;
  trust_ref?: GestaltRef;
  standing_ref?: GestaltRef;             // required; refused if missing
  conflict_policy_hash?: string;
  public_key_hash?: string;
  public_key_algorithm: string;          // expected: "ES256"
  public_key_uncompressed_hex?: string;
  fixture: boolean;                       // must be true
  reviewer_conflict: boolean;             // refused if true
  raw_reviewer_notes?: unknown;           // refused if present
}

Response

{
  "operation": "authority.package.reviewer.onboard",
  "outcome": "admitted",
  "body": {
    "reviewer_trust": "authority_reviewer_trust:...",
    "reviewer": "professional_reviewer:fixture_authority_reviewer",
    "standing": "standing:fixture_reviewer_standing",
    "conflict_policy_hash": "sha256:...",
    "public_verification_material": {
      "public_key_algorithm": "ES256",
      "public_key_hash": "sha256:...",
      "public_key_uncompressed_hex": "...",
      "external_signature_verification_supported": true,
      "private_key_material_exposed": false
    },
    "reviewer_conflict": false,
    "raw_reviewer_notes_stored": false,
    "durable_state": {...},
    "production_admission": false
  },
  "receipt": {...}
}

The handler refuses with authority_package_reviewer_standing_missing if standing_ref is not supplied, authority_package_reviewer_conflict if reviewer_conflict is true, authority_package_reviewer_trust_missing if fixture is false or raw_reviewer_notes is supplied, and authority_package_trust_public_key_invalid for ES256 key mismatches.

SDK example

const reviewer = await client.packageReviewerOnboard({
  tenant: "tenant_node:rheinwerk_calibration",
  reviewer_ref: "professional_reviewer:fixture_authority_reviewer",
  standing_ref: "standing:fixture_reviewer_standing",
  conflict_policy_hash: "sha256:fixture_reviewer_conflict_policy",
  public_key_hash: "sha256:fixture_reviewer_public_key",
  public_key_algorithm: "ES256",
  fixture: true,
  reviewer_conflict: false,
});

Refusal codes

Selected refusal codes returned by this cluster (see refusal.codes for the full list):

authority_package_publisher_trust_missing
authority_package_publisher_private_key_refused
authority_package_reviewer_trust_missing
authority_package_reviewer_standing_missing
authority_package_reviewer_conflict
authority_package_trust_public_key_invalid

Where to read next

• API: authority — authority.package.import, authority.package.candidate, authority.package.review, authority.package.activate, authority.package.revoke, authority.package.status — the operations these onboarding records feed.
• Reference: refusal codes.