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
| Variable | Production | Development |
|---|---|---|
PAS_PLIMS_API_URL | https://accounts.ppoppo.com/plims | http://localhost:3103 |
PAS_ISSUER | https://accounts.ppoppo.com | http://localhost:3100 |
PAS_PLIMS_CLIENT_ID / PAS_PLIMS_CLIENT_SECRET | the 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 set | numbers read | numbers write | aliases read | aliases write | masks write | dependents 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
PasPlimsClientBuildertakes, 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
Errorcarries whole — itsdetailis the context, itssource()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. - Endpoint
Error - What
PasPlimsClientBuilder::newreturns for a malformedapi_url, andAppCredential::newfor a malformed issuer — refused at construction, before anything dials; never anError, so no retry policy ever reads a configuration mistake as a transient failure.EndpointError::endpointsays 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. - PasPlims
Client - Phantom-typed gRPC client for the PLIMS Developer ops face (
:3103). - PasPlims
Client Builder - 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 ofError::Refused, never a return type of its own. - Wire
Status - The status name an
Errorcarries when the call reached the server (Error::wire) — opaque, for logs and messages; branch onRejectionor 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§
- Discovery
Error - 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’sfor_issuerconstructor returns. - Endpoint
- Which configured URL an
EndpointErrorrefused — the face’s address (Api) or PAS’s issuer (Issuer). Which configured URL a refusal is about — the half of anEndpointErrorthat says which one was wrong. - EnvError
- What
PasPlimsClientBuilder::from_envreturns 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::Refusedmeans — the return type ofError::rejection, doored besideErrorso 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, andFault’sis_credential/is_retryable):