Expand description
Read a token that knos-oidc verified. knos-oidc is a Solana program that checks the RS256 signature of an OIDC token (GitHub Actions, GitLab CI, any other RS256 issuer it admitted) on chain and leaves the result in an account it owns. Your program takes that account and reads the claims the issuer signed: which repository, which commit, which workflow, which audience. There is no CPI and no oracle.
This crate has no dependency and does not allocate: bytes in, values out. It works with solana-program, pinocchio or anchor of any version, and off chain.
There are two deployments of knos-oidc, and this crate reads the SECOND unless you name the first: ID,
Token::read and Token::read_any are the second deployment’s (v2 is the same thing by name). It admits
signing keys on GitHub’s own signature, lets them expire and lets a guardian revoke them; it is upgradeable only
through a multisig with a public 48-hour delay, until an outside review. The first deployment (v1::ID,
v1::read) is immutable: no key of it expires and none can be revoked, so a program reads it only by naming it.
A token account has the same layout under both; a token one deployment verified says nothing under the other.
let data = token_account.try_borrow_data()?;
let tok = Token::read(&token_account.owner.to_bytes(), &data, clock.unix_timestamp).map_err(|_| MyError::Token)?;
if tok.issuer() != ISSUER_GITHUB { return Err(MyError::Token.into()); }
let repo = tok.claim_u64("repository_id").ok_or(MyError::Claims)?;Modules§
- v1
- The first deployment of knos-oidc: immutable, with GitHub’s and GitLab’s keys of its day fixed in it, no expiry
and no revocation. Nothing in this crate reads it unless you write
v1. - v2
- The second deployment of knos-oidc by name: the same address and the same reader as the crate’s defaults, for a program that wants its choice written out.
Structs§
- Raw
- A claim’s value as it stands in the JSON: the raw content of a string, or the raw token of a number/literal.
- Text
- A string claim’s text, read without copying it. Its escapes were checked by
text, so reading it cannot fail. - Text
Bytes - Token
- A verified, fresh token.
readdoes the three checks every consumer must do: the account is owned by knos-oidc (the second deployment, unless you read withv1::readorread_from), it is VERIFIED, and it is at mostLATEseconds past its expiry (nowis the chain’s clock). - Verified
- What a token account holds once it is VERIFIED: the issuer’s number, the expiry, and the decoded claims (JSON).
Enums§
- Error
- Why a token or a claim was refused.
code()is the number to put in a program error: 61 to 63 are the codes knos-oidc’s own claims reader returns for the same bytes.
Constants§
- F_
APPROVED - F_
GENESIS - F_
PRIVATE - F_
REVOKED - ID
- The knos-oidc program this crate reads by default: the second deployment (devnet), as bytes. A token account must be owned by it.
- ID_STR
- The same address as Solana prints it.
- ISSUERS
- The
issclaim of each numbered issuer, by its number. - ISSUER_
GITHUB - ISSUER_
GITLAB - ISSUER_
OTHER - Any other RS256 issuer that the second deployment admitted on an attestation (RegisterIssuerKey). The number says
only “not GitHub, not GitLab”: which issuer is
Token::issuer_hash(sha256 of its URL), and knos-oidc checked that the token’sissis that URL. - ISSUER_
PRIVATE - A PRIVATE key verified the token: a key some wallet registered itself, with no attestation (RegisterPrivateKey),
for an issuer no public runner can reach. Nobody vouches for it.
Token::readrefuses such a token; a program that wants them reads withToken::read_anyand accepts one only from aregistrantit trusts for that purpose. - K_
ACTIVE - K_
EXPIRES - K_FLAGS
- K_HDR
- K_STATE
- LATE
- How long after its
expa token is still accepted by knos-oidc and byfresh. The issuers’ tokens live five minutes, which is shorter than it can take to land the transactions that verify one. - MAX_JWT
- The longest token knos-oidc takes.
- T_DONE
- T_EXP
- T_ID
- T_IHASH
- In a VERIFIED account whose issuer is ISSUER_OTHER or ISSUER_PRIVATE: sha256 of the issuer’s URL, and for a private key the wallet that registered it (zero otherwise). They stand where the running power was.
- T_
ISSUER - T_JWT
- T_KEY
- T_LEN
- T_LIMBS
- T_PAYER
- T_PLEN
- T_POFF
- T_
REGISTRANT - T_STAGE
- T_X
- VERIFIED
Functions§
- b58_32
- A canonical base58 32-byte public key (as Solana prints it); None for anything else.
- fields
- One pass over a flat JSON object: for each wanted top-level key, its value. A wanted key that appears twice is refused, the whole object must parse, and nothing may follow it. A key is compared as the text it spells (its escapes decoded), so that this reader and any other JSON reader find the same claim under the same name. The same code as the second knos-oidc’s, so it gives the same answer on the same bytes.
- fresh
- is_hex
- key_
usable - knos-oidc’s rule for a ready key, from its flags and times: revoked first, then not active (not a genesis key, not approved, not private, or before its time), then expired.
- number
- A non-negative integer claim, given as a JSON number or as a string of digits (GitHub sends ids as strings). No sign, no leading zero, no fraction; at most 18 digits.
- parse_
u64 - parts
- Splits
son ‘:’ into exactly N parts. - text
- A string claim’s text. JSON escapes for printable ASCII are decoded (/ \ " and \u00XX), so a value compares equal however the issuer chose to escape it; any other escape is refused.
- unhex32
- verified
- None unless the account’s bytes are a VERIFIED token. The caller must have checked the account’s owner.