Skip to main content

Crate knos_oidc_interface

Crate knos_oidc_interface 

Source
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.
TextBytes
Token
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).
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 iss claim 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’s iss is 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::read refuses such a token; a program that wants them reads with Token::read_any and accepts one only from a registrant it trusts for that purpose.
K_ACTIVE
K_EXPIRES
K_FLAGS
K_HDR
K_STATE
LATE
How long after its exp a token is still accepted by knos-oidc and by fresh. 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 s on ‘:’ 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.