use proc_macro2::{Span, TokenStream as TokenStream2};
use quote::{format_ident, quote};
use syn::{
punctuated::Punctuated, spanned::Spanned, Attribute, Data, DeriveInput, Expr, ExprArray,
ExprLit, Field, Fields, Ident, Lit, Meta, MetaNameValue, Token, Type,
};
#[derive(Debug)]
struct CredentialAttr {
span: Span,
kind: KindValue,
attach_as: AttachmentSiteValue,
scheme: Option<String>,
scopes: Vec<String>,
refresh_via: Option<String>,
revoke_via: Option<String>,
#[allow(dead_code)]
sensitive: bool,
}
#[derive(Debug, Clone)]
enum KindValue {
Closed(ClosedKind),
Other(String),
}
#[derive(Debug, Clone, Copy)]
enum ClosedKind {
Bearer,
Cookie,
OauthAccess,
OauthRefresh,
OidcId,
AwsSts,
Macaroon,
}
impl ClosedKind {
fn parse(s: &str) -> Option<Self> {
match s {
"bearer" => Some(Self::Bearer),
"cookie" => Some(Self::Cookie),
"oauth_access" => Some(Self::OauthAccess),
"oauth_refresh" => Some(Self::OauthRefresh),
"oidc_id" => Some(Self::OidcId),
"aws_sts" => Some(Self::AwsSts),
"macaroon" => Some(Self::Macaroon),
_ => None,
}
}
fn variant_ident(self) -> &'static str {
match self {
Self::Bearer => "Bearer",
Self::Cookie => "Cookie",
Self::OauthAccess => "OauthAccess",
Self::OauthRefresh => "OauthRefresh",
Self::OidcId => "OidcId",
Self::AwsSts => "AwsSts",
Self::Macaroon => "Macaroon",
}
}
}
#[derive(Debug, Clone)]
enum AttachmentSiteValue {
Header(String),
Cookie(String),
FirstFrame { setup_method: String, param: String },
InRpcParam(String),
}
impl AttachmentSiteValue {
fn parse(s: &str) -> Result<Self, ()> {
if let Some(name) = s.strip_prefix("header:") {
if name.is_empty() {
return Err(());
}
Ok(Self::Header(name.to_owned()))
} else if let Some(name) = s.strip_prefix("cookie:") {
if name.is_empty() {
return Err(());
}
Ok(Self::Cookie(name.to_owned()))
} else if let Some(name) = s.strip_prefix("in_rpc_param:") {
if name.is_empty() {
return Err(());
}
Ok(Self::InRpcParam(name.to_owned()))
} else if let Some(rest) = s.strip_prefix("first_frame:") {
let mut iter = rest.splitn(2, ':');
let setup_method = iter.next().ok_or(())?;
let param = iter.next().ok_or(())?;
if setup_method.is_empty() || param.is_empty() {
return Err(());
}
Ok(Self::FirstFrame {
setup_method: setup_method.to_owned(),
param: param.to_owned(),
})
} else {
Err(())
}
}
}
fn is_valid_method_path(s: &str) -> bool {
if s.is_empty() {
return false;
}
let segments: Vec<&str> = s.split('.').collect();
if segments.len() < 2 {
return false;
}
for seg in segments {
if seg.is_empty() {
return false;
}
let mut chars = seg.chars();
match chars.next() {
Some(c) if c.is_ascii_lowercase() => {}
_ => return false,
}
for c in chars {
if !(c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_') {
return false;
}
}
}
true
}
fn parse_credential_attr(attr: &Attribute) -> syn::Result<CredentialAttr> {
let span = attr.span();
let metas: Punctuated<Meta, Token![,]> = match &attr.meta {
Meta::Path(_) => Punctuated::new(),
Meta::List(list) => list.parse_args_with(Punctuated::parse_terminated)?,
Meta::NameValue(nv) => {
return Err(syn::Error::new_spanned(
nv,
"`#[credential]` expects a parenthesized argument list, \
e.g. `#[credential(kind = \"bearer\", attach_as = \"header:authorization\")]`",
));
}
};
let mut kind: Option<KindValue> = None;
let mut attach_as: Option<AttachmentSiteValue> = None;
let mut scheme: Option<String> = None;
let mut scopes: Vec<String> = Vec::new();
let mut refresh_via: Option<String> = None;
let mut revoke_via: Option<String> = None;
let mut sensitive_flag = false;
for meta in metas {
let path = meta.path().clone();
let ident = path
.get_ident()
.ok_or_else(|| syn::Error::new_spanned(&path, "expected a bare identifier"))?
.clone();
let name = ident.to_string();
match name.as_str() {
"kind" => {
kind = Some(parse_kind(&meta)?);
}
"attach_as" => {
let s = expect_str_value(&meta, "attach_as")?;
attach_as = Some(AttachmentSiteValue::parse(&s).map_err(|()| {
syn::Error::new(
meta.span(),
format!(
"invalid `attach_as` value `{s}`. \
Valid forms: \
`\"header:<name>\"`, \
`\"cookie:<name>\"`, \
`\"first_frame:<setup-method>:<param>\"`, \
`\"in_rpc_param:<name>\"`"
),
)
})?);
}
"scheme" => {
scheme = Some(expect_str_value(&meta, "scheme")?);
}
"scopes" => {
scopes = parse_scope_list(&meta)?;
}
"refresh_via" => {
let s = expect_str_value(&meta, "refresh_via")?;
if !is_valid_method_path(&s) {
return Err(syn::Error::new(
meta.span(),
format!(
"invalid `refresh_via` value `{s}`. \
Expected a MethodPath of the form \
`<namespace>.<method>[.<subsegment>]*` where each \
segment matches `[a-z][a-z0-9_]*`."
),
));
}
refresh_via = Some(s);
}
"revoke_via" => {
let s = expect_str_value(&meta, "revoke_via")?;
if !is_valid_method_path(&s) {
return Err(syn::Error::new(
meta.span(),
format!(
"invalid `revoke_via` value `{s}`. \
Expected a MethodPath of the form \
`<namespace>.<method>[.<subsegment>]*` where each \
segment matches `[a-z][a-z0-9_]*`."
),
));
}
revoke_via = Some(s);
}
"sensitive" => {
if matches!(&meta, Meta::Path(_)) {
sensitive_flag = true;
} else if let Meta::NameValue(MetaNameValue { value, .. }) = &meta {
if let Expr::Lit(ExprLit {
lit: Lit::Bool(b), ..
}) = value
{
sensitive_flag = b.value();
} else {
return Err(syn::Error::new(
meta.span(),
"expected `sensitive` or `sensitive = true|false`",
));
}
} else {
return Err(syn::Error::new(
meta.span(),
"expected `sensitive` or `sensitive = true|false`",
));
}
}
"expires_at" => {
return Err(syn::Error::new(
meta.span(),
"`expires_at` cannot be declared on the attribute โ it is \
set at credential mint time, not compile time.",
));
}
other => {
return Err(syn::Error::new(
meta.span(),
format!(
"unknown clause `{other}` in `#[credential(...)]`. \
Valid clauses: \
`kind`, `attach_as`, `scheme`, `scopes`, \
`refresh_via`, `revoke_via`, `sensitive`."
),
));
}
}
}
let kind = kind.ok_or_else(|| {
syn::Error::new(
span,
"missing required clause `kind` in `#[credential(...)]`. \
Example: `kind = \"bearer\"`.",
)
})?;
let attach_as = attach_as.ok_or_else(|| {
syn::Error::new(
span,
"missing required clause `attach_as` in `#[credential(...)]`. \
Example: `attach_as = \"header:authorization\"`.",
)
})?;
Ok(CredentialAttr {
span,
kind,
attach_as,
scheme,
scopes,
refresh_via,
revoke_via,
sensitive: sensitive_flag,
})
}
fn parse_kind(meta: &Meta) -> syn::Result<KindValue> {
match meta {
Meta::NameValue(MetaNameValue { value, .. }) => {
let s = match value {
Expr::Lit(ExprLit {
lit: Lit::Str(s), ..
}) => s.value(),
other => {
return Err(syn::Error::new_spanned(
other,
"`kind` must be a string literal or a structured `{ other = \"...\" }` form",
));
}
};
if s == "other" {
return Err(syn::Error::new(
value.span(),
"the bare form `kind = \"other\"` is not accepted. \
For backend-specific kinds use the structured form: \
`kind(other = \"<your-kind-name>\")` (parens), \
because the `Other` variant of `CredentialKind` carries \
a name parameter and cannot be expressed as a bare string.",
));
}
if let Some(closed) = ClosedKind::parse(&s) {
Ok(KindValue::Closed(closed))
} else {
Err(syn::Error::new(
value.span(),
format!(
"unknown credential kind `{s}`. \
Valid forms: \
`\"bearer\"`, `\"cookie\"`, `\"oauth_access\"`, \
`\"oauth_refresh\"`, `\"oidc_id\"`, `\"aws_sts\"`, \
`\"macaroon\"`, or the structured \
`kind(other = \"<name>\")` escape valve."
),
))
}
}
Meta::List(list) => {
let metas: Punctuated<Meta, Token![,]> =
list.parse_args_with(Punctuated::parse_terminated)?;
let mut name: Option<String> = None;
for inner in metas {
let path = inner.path().clone();
let id = path
.get_ident()
.ok_or_else(|| syn::Error::new_spanned(&path, "expected bare identifier"))?
.clone();
if id == "other" {
name = Some(expect_str_value(&inner, "other")?);
} else {
return Err(syn::Error::new(
inner.span(),
"in the structured `kind(...)` form, only the \
`other = \"<name>\"` clause is supported (use the \
bare `kind = \"bearer\"`-style form for the closed \
CredentialKind variants).",
));
}
}
let name = name.ok_or_else(|| {
syn::Error::new_spanned(
list,
"structured `kind(...)` form must include `other = \"<name>\"`",
)
})?;
Ok(KindValue::Other(name))
}
Meta::Path(p) => Err(syn::Error::new_spanned(
p,
"`kind` requires a value: `kind = \"bearer\"` or `kind(other = \"<name>\")`",
)),
}
}
fn expect_str_value(meta: &Meta, clause: &str) -> syn::Result<String> {
if let Meta::NameValue(MetaNameValue { value, .. }) = meta {
if let Expr::Lit(ExprLit {
lit: Lit::Str(s), ..
}) = value
{
return Ok(s.value());
}
return Err(syn::Error::new(
value.span(),
format!("`{clause}` must be a string literal"),
));
}
Err(syn::Error::new(
meta.span(),
format!("`{clause}` must be of the form `{clause} = \"...\"`"),
))
}
fn parse_scope_list(meta: &Meta) -> syn::Result<Vec<String>> {
match meta {
Meta::NameValue(MetaNameValue { value, .. }) => {
if let Expr::Array(ExprArray { elems, .. }) = value {
let mut out = Vec::with_capacity(elems.len());
for e in elems {
if let Expr::Lit(ExprLit {
lit: Lit::Str(s), ..
}) = e
{
out.push(s.value());
} else {
return Err(syn::Error::new(
e.span(),
"`scopes` entries must be string literals",
));
}
}
Ok(out)
} else {
Err(syn::Error::new(
value.span(),
"`scopes` must be an array of string literals, e.g. `scopes = [\"a.b\", \"c.d\"]`",
))
}
}
other => Err(syn::Error::new(
other.span(),
"`scopes` must be of the form `scopes = [\"...\", ...]`",
)),
}
}
fn type_is_credential_wrapper(ty: &Type) -> bool {
if let Type::Path(tp) = ty {
if let Some(seg) = tp.path.segments.last() {
if seg.ident == "Credential" {
return matches!(seg.arguments, syn::PathArguments::AngleBracketed(_));
}
}
}
false
}
#[derive(Debug)]
struct ParsedCredentialField {
name: String,
variant: Option<String>,
attr: CredentialAttr,
}
pub fn expand_credentials_derive(
item_tokens: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
let input: DeriveInput = match syn::parse(item_tokens) {
Ok(i) => i,
Err(e) => return e.to_compile_error().into(),
};
match expand_impl(input) {
Ok(ts) => ts.into(),
Err(e) => e.to_compile_error().into(),
}
}
fn expand_impl(input: DeriveInput) -> syn::Result<TokenStream2> {
let type_ident = input.ident.clone();
let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
let mut parsed_fields: Vec<ParsedCredentialField> = Vec::new();
match &input.data {
Data::Struct(s) => collect_from_fields_readonly(&s.fields, None, &mut parsed_fields)?,
Data::Enum(e) => {
for variant in &e.variants {
let variant_name = variant.ident.to_string();
collect_from_fields_readonly(
&variant.fields,
Some(variant_name),
&mut parsed_fields,
)?;
}
}
Data::Union(_) => {
return Err(syn::Error::new_spanned(
&input,
"#[derive(Credentials)] cannot be applied to a union",
));
}
}
let registry_fn_name = format_ident!("__plexus_credential_marker_for_{}", type_ident);
let sensitive_fn_name = format_ident!("__plexus_sensitive_fields_for_{}", type_ident);
let registry_entries = parsed_fields
.iter()
.map(emit_field_marker_initializer)
.collect::<Vec<_>>();
let sensitive_entries = parsed_fields
.iter()
.map(|p| {
let name = &p.name;
let variant = match &p.variant {
Some(v) => quote! { ::core::option::Option::Some(#v) },
None => quote! { ::core::option::Option::None },
};
quote! { (#variant, #name) }
})
.collect::<Vec<_>>();
let auth_core: syn::Path = crate::codegen::resolve_auth_core_path(proc_macro2::Span::call_site())
.unwrap_or_else(|| syn::parse_quote!(::plexus_auth_core));
Ok(quote! {
#[doc(hidden)]
#[allow(non_snake_case, dead_code)]
pub fn #registry_fn_name() -> ::std::vec::Vec<CredentialFieldMarker> {
::std::vec![ #( #registry_entries ),* ]
}
#[doc(hidden)]
#[allow(non_snake_case, dead_code)]
pub fn #sensitive_fn_name() -> ::std::vec::Vec<(::core::option::Option<&'static str>, &'static str)> {
::std::vec![ #( #sensitive_entries ),* ]
}
#[allow(non_snake_case, dead_code)]
impl #impl_generics #auth_core::HasCredentialMarkers
for #type_ident #ty_generics #where_clause
{
fn credential_markers() -> &'static [#auth_core::CredentialFieldMarker] {
static __PLEXUS_MARKER_SLICE: ::std::sync::OnceLock<::std::vec::Vec<#auth_core::CredentialFieldMarker>> =
::std::sync::OnceLock::new();
__PLEXUS_MARKER_SLICE
.get_or_init(|| #registry_fn_name())
.as_slice()
}
}
})
}
fn collect_from_fields_readonly(
fields: &Fields,
variant: Option<String>,
out: &mut Vec<ParsedCredentialField>,
) -> syn::Result<()> {
match fields {
Fields::Named(named) => {
for f in named.named.iter() {
process_one_field_ro(f, variant.clone(), out)?;
}
}
Fields::Unnamed(unnamed) => {
for (i, f) in unnamed.unnamed.iter().enumerate() {
if !has_credential_attr(f) {
continue;
}
let attr = read_credential_attr(f)?;
enforce_wrapper_type(f, &attr)?;
out.push(ParsedCredentialField {
name: i.to_string(),
variant: variant.clone(),
attr,
});
}
}
Fields::Unit => {}
}
Ok(())
}
fn process_one_field_ro(
field: &Field,
variant: Option<String>,
out: &mut Vec<ParsedCredentialField>,
) -> syn::Result<()> {
if !has_credential_attr(field) {
return Ok(());
}
let attr = read_credential_attr(field)?;
enforce_wrapper_type(field, &attr)?;
let name = field
.ident
.as_ref()
.map(|i| i.to_string())
.unwrap_or_else(|| "_".to_owned());
out.push(ParsedCredentialField {
name,
variant,
attr,
});
Ok(())
}
fn read_credential_attr(field: &Field) -> syn::Result<CredentialAttr> {
let mut matched: Vec<&Attribute> = field.attrs.iter().filter(|a| is_credential_attr(a)).collect();
if matched.len() > 1 {
return Err(syn::Error::new_spanned(
matched[1],
"two `#[credential(...)]` attributes on the same field. \
Combine the clauses into a single attribute.",
));
}
let attr = matched.remove(0);
parse_credential_attr(attr)
}
fn has_credential_attr(field: &Field) -> bool {
field.attrs.iter().any(is_credential_attr)
}
fn is_credential_attr(attr: &Attribute) -> bool {
attr.path().is_ident("credential")
}
fn enforce_wrapper_type(field: &Field, attr: &CredentialAttr) -> syn::Result<()> {
if !type_is_credential_wrapper(&field.ty) {
let field_label = field
.ident
.as_ref()
.map(|i| format!("`{i}`"))
.unwrap_or_else(|| "tuple field".to_string());
return Err(syn::Error::new(
attr.span,
format!(
"`#[credential(...)]` may only be applied to a field whose type is \
`Credential<T>` (the sealed wrapper from `plexus_auth_core`). \
Field {field_label} has a non-`Credential<T>` type. \
Wrap the payload as `Credential<{}>` and mint via the framework-injected \
`CredentialMinter`.",
describe_type(&field.ty),
),
));
}
Ok(())
}
fn describe_type(ty: &Type) -> String {
match ty {
Type::Path(tp) => tp
.path
.segments
.last()
.map(|s| s.ident.to_string())
.unwrap_or_else(|| "?".to_string()),
_ => "?".to_owned(),
}
}
fn emit_field_marker_initializer(p: &ParsedCredentialField) -> TokenStream2 {
let name = &p.name;
let variant_expr = match &p.variant {
Some(v) => quote! { ::core::option::Option::Some(#v) },
None => quote! { ::core::option::Option::None },
};
let kind_expr = emit_kind(&p.attr.kind);
let attach_as_expr = emit_attach_as(&p.attr.attach_as);
let scheme_expr = match &p.attr.scheme {
Some(s) => quote! { ::core::option::Option::Some(CredentialScheme::new(#s)) },
None => quote! { ::core::option::Option::None },
};
let scopes_iter = p.attr.scopes.iter();
let scopes_expr = quote! {
::std::vec![ #( Scope::new(#scopes_iter) ),* ]
};
let refresh_expr = match &p.attr.refresh_via {
Some(s) => quote! {
::core::option::Option::Some(
MethodPath::try_new(#s).expect("validated at macro time")
)
},
None => quote! { ::core::option::Option::None },
};
let revoke_expr = match &p.attr.revoke_via {
Some(s) => quote! {
::core::option::Option::Some(
MethodPath::try_new(#s).expect("validated at macro time")
)
},
None => quote! { ::core::option::Option::None },
};
quote! {
CredentialFieldMarker {
variant: #variant_expr,
field: #name,
kind: #kind_expr,
attach_as: #attach_as_expr,
scheme: #scheme_expr,
scopes: #scopes_expr,
refresh_via: #refresh_expr,
revoke_via: #revoke_expr,
}
}
}
fn emit_kind(k: &KindValue) -> TokenStream2 {
match k {
KindValue::Closed(c) => {
let v = Ident::new(c.variant_ident(), Span::call_site());
quote! { CredentialKind::#v }
}
KindValue::Other(name) => quote! {
CredentialKind::Other { name: CredentialKindName::new(#name) }
},
}
}
fn emit_attach_as(a: &AttachmentSiteValue) -> TokenStream2 {
match a {
AttachmentSiteValue::Header(name) => quote! {
AttachmentSite::Header {
name: HeaderName::try_new(#name).expect("validated at macro time")
}
},
AttachmentSiteValue::Cookie(name) => quote! {
AttachmentSite::Cookie {
name: CookieName::try_new(#name).expect("validated at macro time")
}
},
AttachmentSiteValue::FirstFrame {
setup_method,
param,
} => quote! {
AttachmentSite::FirstFrame {
setup_method: MethodPath::try_new(#setup_method).expect("validated at macro time"),
param: ParamName::new(#param),
}
},
AttachmentSiteValue::InRpcParam(param) => quote! {
AttachmentSite::InRpcParam { param: ParamName::new(#param) }
},
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn method_path_validator_accepts_canonical() {
assert!(is_valid_method_path("auth.login"));
assert!(is_valid_method_path("cone.send_message"));
assert!(is_valid_method_path("a.b.c.d"));
}
#[test]
fn method_path_validator_rejects_bad() {
assert!(!is_valid_method_path(""));
assert!(!is_valid_method_path("login"));
assert!(!is_valid_method_path("Auth.login"));
assert!(!is_valid_method_path("1auth.login"));
assert!(!is_valid_method_path("auth..login"));
assert!(!is_valid_method_path("auth."));
assert!(!is_valid_method_path(".login"));
assert!(!is_valid_method_path("auth.*"));
}
#[test]
fn closed_kind_parser() {
assert!(matches!(ClosedKind::parse("bearer"), Some(ClosedKind::Bearer)));
assert!(matches!(ClosedKind::parse("cookie"), Some(ClosedKind::Cookie)));
assert!(matches!(
ClosedKind::parse("oauth_access"),
Some(ClosedKind::OauthAccess)
));
assert!(matches!(
ClosedKind::parse("oauth_refresh"),
Some(ClosedKind::OauthRefresh)
));
assert!(matches!(ClosedKind::parse("oidc_id"), Some(ClosedKind::OidcId)));
assert!(matches!(ClosedKind::parse("aws_sts"), Some(ClosedKind::AwsSts)));
assert!(matches!(
ClosedKind::parse("macaroon"),
Some(ClosedKind::Macaroon)
));
assert!(ClosedKind::parse("other").is_none());
assert!(ClosedKind::parse("nonsense").is_none());
}
#[test]
fn attachment_site_parser_accepts_all_four_forms() {
assert!(matches!(
AttachmentSiteValue::parse("header:authorization"),
Ok(AttachmentSiteValue::Header(ref s)) if s == "authorization"
));
assert!(matches!(
AttachmentSiteValue::parse("cookie:plexus_session"),
Ok(AttachmentSiteValue::Cookie(ref s)) if s == "plexus_session"
));
match AttachmentSiteValue::parse("first_frame:auth.connect:token") {
Ok(AttachmentSiteValue::FirstFrame {
setup_method,
param,
}) => {
assert_eq!(setup_method, "auth.connect");
assert_eq!(param, "token");
}
other => panic!("expected FirstFrame, got {other:?}"),
}
assert!(matches!(
AttachmentSiteValue::parse("in_rpc_param:session_token"),
Ok(AttachmentSiteValue::InRpcParam(ref s)) if s == "session_token"
));
}
#[test]
fn attachment_site_parser_rejects_bad_forms() {
assert!(AttachmentSiteValue::parse("").is_err());
assert!(AttachmentSiteValue::parse("header").is_err()); assert!(AttachmentSiteValue::parse("header:").is_err()); assert!(AttachmentSiteValue::parse("cookie:").is_err());
assert!(AttachmentSiteValue::parse("body:foo").is_err()); assert!(AttachmentSiteValue::parse("first_frame:auth.connect").is_err()); assert!(AttachmentSiteValue::parse("first_frame::token").is_err()); }
#[test]
fn type_is_credential_wrapper_accepts_credential_t() {
let ty: Type = syn::parse_str("Credential<String>").unwrap();
assert!(type_is_credential_wrapper(&ty));
let ty: Type = syn::parse_str("plexus_auth_core::Credential<SessionToken>").unwrap();
assert!(type_is_credential_wrapper(&ty));
}
#[test]
fn type_is_credential_wrapper_rejects_other_types() {
let ty: Type = syn::parse_str("String").unwrap();
assert!(!type_is_credential_wrapper(&ty));
let ty: Type = syn::parse_str("Option<Credential<String>>").unwrap();
assert!(!type_is_credential_wrapper(&ty));
let ty: Type = syn::parse_str("Credential").unwrap();
assert!(!type_is_credential_wrapper(&ty));
}
}