Skip to main content

Token

Struct Token 

Source
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), and runner_environment if 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>

Source

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.

Source

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).

Source

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.

Source

pub fn read_any_from( program: &[u8; 32], owner: &[u8; 32], data: &'a [u8], now: i64, ) -> Result<Token<'a>, Error>

Source

pub fn issuer(&self) -> u8

ISSUER_GITHUB, ISSUER_GITLAB, ISSUER_OTHER (see issuer_hash) or ISSUER_PRIVATE (see registrant).

Source

pub fn exp(&self) -> i64

Source

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.

Source

pub fn registrant(&self) -> Option<&'a [u8; 32]>

The wallet that registered the private key; None for a token that is not private.

Source

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.

Source

pub fn key(&self) -> &'a [u8; 32]

The address of the key account that verified the token.

Source

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.

Source

pub fn payload(&self) -> &'a [u8]

The claims as the issuer signed them (a JSON object).

Source

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.

Source

pub fn claim(&self, name: &str) -> Option<Text<'a>>

A string claim. None if it is absent, appears twice or is not a string.

Source

pub fn claim_u64(&self, name: &str) -> Option<u64>

A non-negative integer claim, given as a number or as a string of digits (GitHub sends ids as strings).

Source

pub fn audience(&self) -> Option<Text<'a>>

The aud claim when it is one string, which is what GitHub Actions and GitLab CI sign.

Trait Implementations§

Source§

impl<'a> Clone for Token<'a>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<'a> Copy for Token<'a>

Source§

impl<'a> Debug for Token<'a>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a> Freeze for Token<'a>

§

impl<'a> RefUnwindSafe for Token<'a>

§

impl<'a> Send for Token<'a>

§

impl<'a> Sync for Token<'a>

§

impl<'a> Unpin for Token<'a>

§

impl<'a> UnsafeUnpin for Token<'a>

§

impl<'a> UnwindSafe for Token<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.