Skip to main content

Crate ppoppo_pas_plims

Crate ppoppo_pas_plims 

Source
Expand description

§ppoppo-pas-plims

Ppoppo Accounts System (PAS) PLIMS face client for Rust.

The SDK for an app — or an AI agent — that manages Ppoppo numbers through PLIMS (Ppnum Lifecycle & Inventory Management, pas.plims.v1): sub-numbers and the capabilities they declare, aliases, ephemeral masks, and an agent’s dependent agents. It runs on its own client_credentials pair.

  • Issuer-only credential — the token endpoint is read from PAS’s discovery document; the token is minted, cached and re-minted inside the client
  • Phantom-typed scope sets — method availability enforced at compile time, and independently by the server (double lock)
  • Typed identity — Ppnum, PpnumId, CapabilityId, AliasId; a malformed id from the wire is a decode error, never a string that fails later

§Usage

[dependencies]
ppoppo-pas-plims = "0.5"
use ppoppo_pas_plims::credential::{AppCredential, ClientSecret};
use ppoppo_pas_plims::scopes::Registration;
use ppoppo_pas_plims::types::{EntityType, NewCapability, PageRequest, PpnumCell, Reach};
use ppoppo_pas_plims::PasPlimsClientBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PasPlimsClientBuilder::new(
        "https://accounts.ppoppo.com/plims",
        AppCredential::<Registration>::new(
            "https://accounts.ppoppo.com",
            std::env::var("PAS_PLIMS_CLIENT_ID")?,
            ClientSecret::new(std::env::var("PAS_PLIMS_CLIENT_SECRET")?),
        )?,
    )?
    .build()?; // the tier is the credential's

    // Provision a number for an agent and declare what it can do.
    let number = client
        .create_number(EntityType::AiAgent, PpnumCell::durable(Reach::Open))
        .await?;
    client
        .create_capability(&number.ppnum_id, NewCapability::new("summarize", "1.0.0"))
        .await?;

    // Walk the inventory, page by page.
    let mut request = Some(PageRequest::default());
    while let Some(page_request) = request {
        let page = client.list_numbers(page_request.clone()).await?;
        for number in &page.items {
            println!("{}", number.ppnum.display());
        }
        request = page_request.following(&page);
    }
    Ok(())
}

PasPlimsClientBuilder::from_env() reads the same configuration as one set; examples/quickstart.rs runs it. A credential of your own is any credential::TokenSource, built with build_as::<S>().

Every constructor parses and dials nothing: a malformed URL or issuer is an EndpointError at construction, never a retryable failure on the first call.

§Endpoints

VariableProductionDevelopment
PAS_PLIMS_API_URLhttps://accounts.ppoppo.com/plimshttp://localhost:3103
PAS_ISSUERhttps://accounts.ppoppo.comhttp://localhost:3100
PAS_PLIMS_CLIENT_ID / PAS_PLIMS_CLIENT_SECRETthe app’s (or agent’s) pair

Pass the face’s address exactly as PAS spells it: it is the token’s RFC 8707 resource, matched byte for byte (a trailing slash names a different one).

§Scope sets

Construct the client with the scope set your credential holds. Its atoms are sent as the grant’s scope and every grant’s scope echo is checked to cover them, or the call is never dialled: a registered app is minted its registration’s set whatever it asks, and an AI agent asks for exactly Agent’s atom.

Scope setnumbers readnumbers writealiases readaliases writemasks writedependents write
NumbersRead✓—————
NumbersWrite—✓————
AliasesRead——✓———
AliasesWrite———✓——
MasksWrite————✓—
Registration (the default registration)✓✓✓———
RegistrationCeiling (everything an app can register)✓✓✓✓✓—
Agent (an AI agent’s own credential)—————✓

The columns are the capability traits, named after their atom: PlimsNumbersReadCapable (list_numbers, get_number, list_capabilities), PlimsNumbersWriteCapable (create_number, deactivate_number, create_capability, update_capability, delete_capability), PlimsAliasesReadCapable (list_aliases), PlimsAliasesWriteCapable (create_alias), PlimsMasksWriteCapable (create_mask) and PlimsDependentsWriteCapable (create_dependent_agent). Calling a method your scope set does not carry is a compile error, not a runtime PermissionDenied. plims:dependents:write is no app’s: PAS grants it to a credential for being an AI agent.

§Versioning

This crate keeps its own semver: its version moves only when its own public surface (or a dependency that reaches it) changed. Read CHANGELOG.md for what actually moved.

§License

MIT OR Apache-2.0

Re-exports§

pub use ppoppo_clock as clock;

Modules§

credential
What a client presents — the credential a PasPlimsClientBuilder takes, and the vocabulary its sources speak.
scopes
Sealed scope-set type family for crate::PasPlimsClient<S>.
types
Domain types for the PLIMS Developer ops-face client.

Structs§

Cause
A foreign cause an Error carries whole — its detail is the context, its source() the error underneath. A cause the family did not write — a transport’s, a parser’s, a store’s — carried whole, never formatted into a string.
EndpointError
What PasPlimsClientBuilder::new returns for a malformed api_url, and AppCredential::new for a malformed issuer — refused at construction, before anything dials; never an Error, so no retry policy ever reads a configuration mistake as a transient failure. EndpointError::endpoint says which URL was wrong. Vocabulary (ppoppo-call): every gRPC face refuses a dialed URL with this one type. A configured URL, refused where it was handed over — before anything was dialled, fetched or retried.
PasPlimsClient
Phantom-typed gRPC client for the PLIMS Developer ops face (:3103).
PasPlimsClientBuilder
Builder for PasPlimsClient<S>: the face’s address and the credential the client presents there.
Refusal
The payload of an Error::Refused: what the refusal means, the status it came back as, and what the server said. An application-layer refusal: what it means, the status it came back as, and what the server said — the payload of Error::Refused, never a return type of its own.
WireStatus
The status name an Error carries when the call reached the server (Error::wire) — opaque, for logs and messages; branch on Rejection or the predicates instead. The status a server answered with, by its canonical name — for a log line or an error message, never for a branch.

Enums§

DiscoveryError
Why a credential could not read PAS’s discovery document — the payload of credential::TokenSourceError::Discovery, which a token fetch returns. Transient when the fetch failed, terminal when the document cannot be used; never a verdict on the credential. Vocabulary (ppoppo-call), shared with every face that takes an issuer. Why an issuer could not be used to find an endpoint — what every face’s for_issuer constructor returns.
Endpoint
Which configured URL an EndpointError refused — the face’s address (Api) or PAS’s issuer (Issuer). Which configured URL a refusal is about — the half of an EndpointError that says which one was wrong.
EnvError
What PasPlimsClientBuilder::from_env returns when its variables are half-set, not Unicode, or name a malformed URL — a configuration mistake, refused before anything dials. Vocabulary (ppoppo-call): every face reads its environment set by the same rule. A face’s environment variable set, refused.
Error
Every error a ppoppo client returns from a credentialed call.
Rejection
What an Error::Refused means — the return type of Error::rejection, doored beside Error so that reading a refusal never names a transport status or another crate. Branch on this, or on the predicates (is_out_of_sight, is_caller_input, and Fault’s is_credential / is_retryable):