pub struct Token<'a> { /* private fields */ }Expand description
A verified, fresh token. read does the three checks every consumer must do: the account is owned by knos-oidc
(the second deployment, unless you read with v1::read or read_from), it is VERIFIED, and it is at most LATE
seconds past its expiry (now is the chain’s clock).
What remains your program’s job, because knos-oidc only says the token is genuine:
- the issuer (
issuer()): GitHub and GitLab sign different claims; - the claims your statement depends on: the repository (
repository_id), the workflow file and its commit (job_workflow_ref,job_workflow_sha), andrunner_environmentif a self-hosted runner must not count; - the audience: give your program its own prefix and require it, so a token minted for another program cannot be used with yours;
- your own replay guard: the same verified token can be read by any program, any number of times, until an hour after its expiry. Bind the token to one action in the audience and record that the action was done.
- if a revoked or expired signing key must stop its tokens at once: take the key account too and call
check_key. Without it a token account is good for up to 25 hours after its key stopped.
read never returns a token that a PRIVATE key verified. read_any does, and then is_private() is the check
your program must not forget: such a token is the word of registrant(), not of the issuer its claims name.
Implementations§
Source§impl<'a> Token<'a>
impl<'a> Token<'a>
Sourcepub fn read(
owner: &[u8; 32],
data: &'a [u8],
now: i64,
) -> Result<Token<'a>, Error>
pub fn read( owner: &[u8; 32], data: &'a [u8], now: i64, ) -> Result<Token<'a>, Error>
The second deployment’s token accounts (ID). For the first deployment, write v1::read.
Sourcepub fn read_from(
program: &[u8; 32],
owner: &[u8; 32],
data: &'a [u8],
now: i64,
) -> Result<Token<'a>, Error>
pub fn read_from( program: &[u8; 32], owner: &[u8; 32], data: &'a [u8], now: i64, ) -> Result<Token<'a>, Error>
The same three checks against one deployment of knos-oidc that you name: ID or v1::ID. A token that one
deployment verified says nothing under the other’s address, so name exactly the one your program trusts.
A token that a private key verified is refused (Error::Private).
Sourcepub fn read_any(
owner: &[u8; 32],
data: &'a [u8],
now: i64,
) -> Result<Token<'a>, Error>
pub fn read_any( owner: &[u8; 32], data: &'a [u8], now: i64, ) -> Result<Token<'a>, Error>
read, and tokens that a private key verified too. Ask is_private() of what this returns.
pub fn read_any_from( program: &[u8; 32], owner: &[u8; 32], data: &'a [u8], now: i64, ) -> Result<Token<'a>, Error>
Sourcepub fn issuer(&self) -> u8
pub fn issuer(&self) -> u8
ISSUER_GITHUB, ISSUER_GITLAB, ISSUER_OTHER (see issuer_hash) or ISSUER_PRIVATE (see registrant).
pub fn exp(&self) -> i64
Sourcepub fn is_private(&self) -> bool
pub fn is_private(&self) -> bool
Whether a private key verified this token: a key a wallet registered itself, which nobody vouches for. The claims may name any issuer, GitHub included; they are the registrant’s word. True for any issuer number this crate does not know, so that a newer kind of key is never taken for a public one.
Sourcepub fn registrant(&self) -> Option<&'a [u8; 32]>
pub fn registrant(&self) -> Option<&'a [u8; 32]>
The wallet that registered the private key; None for a token that is not private.
Sourcepub fn issuer_hash(&self) -> Option<&'a [u8; 32]>
pub fn issuer_hash(&self) -> Option<&'a [u8; 32]>
sha256 of the issuer’s URL, for ISSUER_OTHER and ISSUER_PRIVATE; None for GitHub and GitLab by number.
Sourcepub fn check_key(
&self,
key_address: &[u8; 32],
key_owner: &[u8; 32],
key_data: &[u8],
now: i64,
) -> Result<(), Error>
pub fn check_key( &self, key_address: &[u8; 32], key_owner: &[u8; 32], key_data: &[u8], now: i64, ) -> Result<(), Error>
Whether the key that verified the token may still verify at now, by knos-oidc’s own rule. Pass the key
account: its address must be the one the token names and its owner the same knos-oidc. Second deployment
only (the first has no expiry and no revocation). Errors: Key, KeyNotActive, KeyExpired, KeyRevoked.
Sourcepub fn claims<const N: usize>(
&self,
want: [&[u8]; N],
) -> Result<[Option<Raw<'a>>; N], Error>
pub fn claims<const N: usize>( &self, want: [&[u8]; N], ) -> Result<[Option<Raw<'a>>; N], Error>
Several claims in one pass over the payload. A wanted claim that appears twice is an error.
Sourcepub fn claim(&self, name: &str) -> Option<Text<'a>>
pub fn claim(&self, name: &str) -> Option<Text<'a>>
A string claim. None if it is absent, appears twice or is not a string.