Struct AuthChallenge 

pub struct AuthChallenge {
    pub id: i64,
    pub user_id: ForeignKey<AuthUser>,
    pub purpose: String,
    pub secret_hash: String,
    pub expires_at: DateTime<Utc>,
    pub attempts: i32,
    pub used_at: Option<DateTime<Utc>>,
    pub created_at: DateTime<Utc>,
}

One pending challenge. The plaintext (6-digit code or opaque token) is never stored — only base64(sha256(plaintext)). Single-use (used_at), time-boxed (expires_at), and (for codes) attempt-capped (attempts).

Fields

id: i64

user_id: ForeignKey<AuthUser>

purpose: String

secret_hash: String

expires_at: DateTime<Utc>

attempts: i32

used_at: Option<DateTime<Utc>>

created_at: DateTime<Utc>

Implementations

impl AuthChallenge

pub fn objects() -> Manager<Self>

impl AuthChallenge

pub const ID: IntCol<Self> = auth_challenge::ID

pub const USER_ID: ForeignKeyCol<Self> = auth_challenge::USER_ID

pub const PURPOSE: StrCol<Self> = auth_challenge::PURPOSE

pub const SECRET_HASH: StrCol<Self> = auth_challenge::SECRET_HASH

pub const EXPIRES_AT: DateTimeCol<Self> = auth_challenge::EXPIRES_AT

pub const ATTEMPTS: IntCol<Self> = auth_challenge::ATTEMPTS

pub const USED_AT: NullableDateTimeCol<Self> = auth_challenge::USED_AT

pub const CREATED_AT: DateTimeCol<Self> = auth_challenge::CREATED_AT

impl AuthChallenge

pub async fn issue( user_id: i64, purpose: &str, plaintext: &str, ttl: Duration, ) -> Result<AuthChallenge, AuthError>

Create and persist a new challenge for user_id.

The plaintext (a 6-digit code or opaque token generated by the caller) is not stored — only its hash_secret digest reaches the database. The challenge is valid for ttl; attempts starts at 0; used_at is None.

Called by

Tasks 8 (email verify) and 9 (password reset) call this.

pub fn is_live(&self) -> bool

true when the challenge has not been consumed (used_at IS NULL) and has not expired (expires_at > now). The in-memory check complements the SQL USED_AT IS NULL filter: expired-but-unused rows are filtered out by this method even if they slipped through (e.g. a race where expires_at passed between the query and the caller).

pub async fn find_active_for_user( user_id: i64, purpose: &str, ) -> Result<Option<AuthChallenge>, AuthError>

Return the most-recently-issued active challenge for (user_id, purpose), or None if no unused, unexpired row exists.

“Active” = USED_AT IS NULL in SQL and is_live() in Rust (the Rust guard catches challenges whose expires_at passed between the query and this call).

ORM note

auth_challenge::USED_AT.is_null() is the SQL IS NULL predicate on the nullable used_at column. order_by takes a single OrderExpr<T> (not a slice) and can be called multiple times to append clauses. Mirror the single-arg idiom from umbral-tasks.

pub async fn find_active_by_secret( plaintext: &str, purpose: &str, ) -> Result<Option<AuthChallenge>, AuthError>

Return the challenge whose stored hash matches hash_secret(plaintext) for the given purpose, or None if no active match exists.

Used by the verification handler: the handler receives the raw plaintext (code or token), this method hashes it and looks up the digest — the plaintext never touches the WHERE clause.

pub async fn mark_used(&self) -> Result<(), AuthError>

Stamp used_at with the current time. After this call, find_active_for_user and find_active_by_secret will not return this challenge. Idempotent in the DB sense (a second call just overwrites with a slightly later timestamp), though callers should treat the challenge as finished after the first call.

pub async fn bump_attempts(&self) -> Result<(), AuthError>

Increment attempts by 1. Call this on each failed verification attempt so the caller can gate on a maximum before locking the challenge. The in-memory self.attempts is NOT updated; re-fetch the row to get the current count.

The increment is an atomic server-side SET attempts = attempts + 1 (via update_expr) — two concurrent calls cannot both read the same stale value and both write the same result, so the attempt cap used by the brute-force guard in Task 8 cannot be under-counted.

Trait Implementations

impl Clone for AuthChallenge

fn clone(&self) -> AuthChallenge

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AuthChallenge

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AuthChallenge

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'a, R: Row> FromRow<'a, R> for AuthChallenge

where &'a str: ColumnIndex<R>, i64: Decode<'a, R::Database> + Type<R::Database>, ForeignKey<AuthUser>: Decode<'a, R::Database> + Type<R::Database>, String: Decode<'a, R::Database> + Type<R::Database>, DateTime<Utc>: Decode<'a, R::Database> + Type<R::Database>, i32: Decode<'a, R::Database> + Type<R::Database>, Option<DateTime<Utc>>: Decode<'a, R::Database> + Type<R::Database>,

fn from_row(__row: &'a R) -> Result<Self>

impl HydrateRelated for AuthChallenge

fn fk_id_for(&self, field_name: &str) -> Option<Value>

Return the raw FK value stored in the field named field_name, or None if the field doesn’t exist on this model or is not a FK.

fn hydrate_fk(&mut self, field_name: &str, row: &Value)

Set ForeignKey<U>.resolved for the field named field_name by deserialising row as the target model type.

fn set_m2m_parent_ids(&mut self)

Set the parent_id cache on every M2M<U> field this model owns. Closes the second BUG-16 gap: without this, m2m.add(&t) silently writes a junction row with parent_id = 0 because the macro skips M2M fields in the FromRow decode path.

fn pk_as_json(&self) -> Option<Value>

Return this row’s primary key as a serde_json::Value, whatever the PK type — i64, String, uuid::Uuid, a custom newtype. The relation-hydration paths (prefetch_related, reverse-FK and reverse-OneToOne collection) bucket children by the parent’s PK, and keying those buckets on a Value (canonicalised via crate::orm::pk_key) lets UUID- and slug-PK models flow through too, not just i64.

fn set_m2m_resolved_json(&mut self, field_name: &str, rows: Vec<Value>)

Attach a list of pre-fetched child rows to the named M2M<U> field’s resolved slot. Called by QuerySet::prefetch_related (gap #19) after a batched JOIN through the junction table returns one Vec per parent.

fn set_reverse_fk_resolved_json(&mut self, field_name: &str, rows: Vec<Value>)

Gap #44 — attach a list of pre-fetched child rows to the named ReverseSet<C> field’s resolved slot. Counterpart to set_m2m_resolved_json but for reverse-FK collections (one parent, many children pointing at it via a FK column).

fn set_one_to_one_resolved_json(&mut self, field_name: &str, row: Option<Value>)

Reverse-OneToOne counterpart to set_reverse_fk_resolved_json. Called by prefetch_related with Some(child_json) when the runtime FK lookup found exactly one matching child, or None when no child matched (the slot still flips is_loaded() to true).

fn take_pending_m2m_into(&mut self, _dest: &mut Self)

Move form-staged M2M pending ids from self into dest, field by field. The typed create() builds its INSERT from the caller’s instance, then reads a fresh row back from the DB (carrying the autoincremented PK) — the pending ids staged by the Form derive live on the caller’s instance, not the readback row. This hook transfers them across so write_pending_m2m on the readback row (which has the real parent_id seeded) finds them. Default: no-op for models with no M2M fields.

fn write_pending_m2m<'a>( &'a mut self, ) -> Pin<Box<dyn Future<Output = Result<(), WriteError>> + Send + 'a>>

Flush form-staged M2M selections to their junction tables after the parent row was inserted. The macro emits a body that walks this model’s M2M fields, reads parent_id + junction_table (seeded by set_m2m_parent_ids) and the pending child ids, and calls set_junction_dynamic. Default: no-op for models with no M2M fields.

impl Model for AuthChallenge

const NAME: &'static str = "AuthChallenge"

The struct name, used by the migration engine (M5) to label snapshot entries and to map autodetected operations back to the model that produced them. The M3 derive emits the struct ident verbatim (“Post”, “Comment”, etc.).

const TABLE: &'static str = "auth_challenge"

The SQL table name. M3’s derive defaults this to the snake_case of the struct name unless #[umbral(table = "...")] overrides it.

const APP_LABEL: &'static str = "app"

The app label (the owning plugin’s name) this model belongs to.

const FIELDS: &'static [FieldSpec]

Static metadata for every field on the model.

const DISPLAY: &'static str = "AuthChallenge"

Human-readable display name for this model, used by the admin sidebar as the default label. Defaults to Self::NAME.

const ICON: &'static str = "database"

Lucide icon slug shown next to this model in the admin sidebar. Defaults to "database". Any valid Lucide icon name works; unknown names are silently ignored by Lucide at render time.

const DATABASE: Option<&'static str> = ::core::option::Option::None

Database alias this model lives on, when the app registers more than one pool via AppBuilder::database(...). None (the default) means “use whatever the owning plugin chose via Plugin::database(), or \"default\" if neither side overrode.”

const SINGLETON: bool = false

Single-row-marker. When true, the admin auto-redirects the list view to the (sole) row’s edit form, hides the “+ New” button, and surfaces the model as a settings-style screen. The single-row settings model pattern. Set via #[umbral(singleton)] on the struct. Closes BUG-9 in bugs/tests/testBugs.md.

const SOFT_DELETE: bool = false

Feature #72 — soft-delete marker. Set via #[umbral(soft_delete)] on the struct. When true, the framework treats this model as having a deleted_at: Option<DateTime<Utc>> column (which the user MUST declare — derive macros can’t add fields to the input struct), and:

const UNIQUE_TOGETHER: &'static [&'static [&'static str]]

Composite-UNIQUE constraints. Each inner slice names a constraint over the listed column names. Set via #[umbral(unique_together = [["a", "b"]])]. Closes BUG-6 in bugs/tests/testBugs.md. Default empty; the migration engine emits one UNIQUE (col1, col2) clause per inner group on CREATE TABLE.

const INDEXES: &'static [&'static [&'static str]]

Multi-column indexes. Each inner slice names an index over the listed columns. Set via #[umbral(indexes = [["tenant_id", "created_at"]])]. Closes BUG-7. Default empty; the migration engine emits CREATE INDEX IF NOT EXISTS idx_<table>_<col1>_<col2> after the CREATE TABLE. Single-column indexes stay on the field attribute (#[umbral(index)]).

const ORDERING: &'static [(&'static str, bool)]

Default ORDER BY clause, applied when a QuerySet terminates without an explicit order_by. Each tuple is (column_name, is_descending). Set via #[umbral(ordering = ["-published_at", "id"])] (leading - flips to DESC). Closes BUG-8. Default empty.

const M2M_RELATIONS: &'static [M2MRelationSpec]

Many-to-many relations declared on this model. Each entry names a field and its target model. The migration engine uses this to auto-generate junction tables; the admin uses it to render M2M pickers. Default empty.

const REVERSE_FK_RELATIONS: &'static [ReverseFkRelationSpec]

Gap #44 — reverse-FK collections declared on this model via #[umbral(reverse_fk = "<fk_col>")] pub <name>: ReverseSet<C>. Each entry tells prefetch_related how to fetch the children: SELECT * FROM <target_table> WHERE <fk_column> IN (parent_pks) then group by <fk_column> value, populate each parent’s ReverseSet.resolved. Default empty; the macro emits one entry per declared ReverseSet<C> field.

const ONE_TO_ONE_RELATIONS: &'static [OneToOneRelationSpec]

Reverse OneToOne accessors declared on this model via pub <name>: OneToOne<C> (no umbral attribute required). Unlike REVERSE_FK_RELATIONS, the FK column on the child is not named at macro time — prefetch_related looks it up at runtime by scanning the child’s FIELDS for the UNIQUE FK pointing back at this model’s table. Exactly one match required; 0 or 2+ matches surface a loud error naming the ambiguity.

type PrimaryKey = i64

The primary-key type. M2 supports i64 only; UUID lands later.

fn primary_key(&self) -> i64

Return the primary key of this instance.

impl Serialize for AuthChallenge

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.