Skip to main content

Crate hyprstream_k8s_pds

Crate hyprstream_k8s_pds 

Source
Expand description

AGPL PDS adapter for hyprstream_k8s::mesh::TenantBinding grant compilation.

A TenantBinding is an admin-authorable surface, never the authority. When hyprstream_k8s::mesh::TenantBindingSpec::entitlement is set, the operator invokes this adapter through hyprstream_k8s::grant::TenantGrantService and compiles it — signing as issuer — into the two artifacts that are the authority:

  1. A UCAN grant ([hyprstream_rpc::auth::ucan::Ucan]) — an issuer→holder capability signed with the project’s hybrid-PQC COSE composite (EdDSA + ML-DSA-65) via [hyprstream_rpc::crypto::cose_sign::sign_composite] with UCAN_AAD. The operator is the issuer; the tenant is the audience/holder.
  2. An ai.hyprstream.ledger.allocation record ([hyprstream_pds::ledger::AllocationRecord]) — the inventory line that lands in the tenant’s PDS, whose grant field references the UCAN’s CID. This is the durable, holder-controlled entitlement; revocation is bumping the epoch (stop renewing + reissue), not editing the CRD.

Enforcers (#781/#787/#790/#793/#794/#527) verify the presented grant (the UCAN CID + its allocation record), never the CRD. TenantGrantVerifier is the verification contract — the exact shape of that consume-side check — so the consumer issues can wire it without re-deriving the compile/verify correspondence.

§What this module deliberately leaves to the consumer issues

Per #929’s narrow scope:

  • PDS publish of the allocation record into the tenant’s MST (the physical “lands in inventory”) — needs the #910 multi-collection write path + the tenant’s signing key, both operator-bootstrap concerns. This module produces the record; landing it is plumbing.
  • Operator issuer-key bootstrap in-cluster — TenantGrantIssuer takes already-resolved key material; deriving it from node_identity’s root store at operator startup is the K5b runtime’s job.
  • Enforcer consumption (admission, receipts, autoscaling bounds) — #781/#787/#790/#793/#794/#527/#792/#795/#784. The compiled grant is the primitive they consume; TenantGrantVerifier is the contract.
  • S6 short-ttl sender-bound (DPoP) renewal — greenfield (#921 gap 2); the epoch counter on the allocation record is the revocation handle until the renewal layer exists.

§Downstream composition

The Apache substrate depends only on its service-neutral contract. A downstream binary enables the substrate’s k8s,grant features, opts into this AGPL adapter, and passes the issuer to the generic operator without contacting a cluster during compilation:

use std::sync::Arc;
use hyprstream_k8s::kube::Client;
use hyprstream_k8s::operator::{
    run_operator_with_grant_service, HyprstreamOperatorRpc, OperatorConfig,
    OperatorError, OperatorState,
};
use hyprstream_k8s_pds::TenantGrantIssuer;

fn configured_state<R: HyprstreamOperatorRpc>(
    client: Client,
    rpc: Arc<R>,
    config: OperatorConfig,
    issuer: TenantGrantIssuer,
) -> OperatorState<R> {
    OperatorState::new(client, rpc, config)
        .with_grant_service(Some(Arc::new(issuer)))
}

async fn run<R: HyprstreamOperatorRpc>(
    client: Client,
    rpc: Arc<R>,
    config: OperatorConfig,
    issuer: TenantGrantIssuer,
) -> Result<(), OperatorError> {
    run_operator_with_grant_service(
        client,
        rpc,
        config,
        Some(Arc::new(issuer)),
    ).await
}

Structs§

CompiledTenantGrant
The output of compiling a TenantBinding: the authority artifacts.
TenantGrantIssuer
The operator’s issuer key material for compiling tenant grants.
TenantGrantVerifier
The verification contract for enforcers (#781/#787/#790/#793/#794/#527).
VerifiedTenantGrant
The verified shape of a compiled tenant grant — the data an enforcer admits against.

Constants§

TENANT_GRANT_ABILITY
The UCAN ability a compiled tenant grant carries.
TENANT_GRANT_ED25519_PURPOSE
HKDF purpose label for the operator’s tenant-grant Ed25519 issuer key.

Functions§

now_unix
Unix seconds from the system wall clock; never panics on platforms without a wall clock (returns 0, which fails the expiry check closed). Used by the operator’s TenantBinding reconcile to stamp not_before and check author-supplied expiries.