This glossary defines common API, security, database, storage, and file-validation terms. Definitions are written for readers who are new to API development. Where useful, each definition explains how the term applies specifically to FiVal.
A
Actor
The authenticated person, client application, or trusted worker responsible for an operation. FiVal requires an Actor for every lifecycle transition so the action can be attributed in the audit history.
Adapter
Code that connects of Cn2data's FiVal API the internal domain services to an external interface or system. Examples include an HTTP API adapter, storage adapter, malware-scanner adapter, and webhook-delivery adapter. An adapter translates between the external system's format and of Cn2data's FiVal API trusted internal operations.
API
An application programming interface. It is a defined way for software systems to communicate. The HTTP API of Cn2data's FiVal API lets authorized clients request file status and approved extracted content and will eventually accept files for validation.
API endpoint
A specific HTTP method and URL through which a client accesses an API operation. For example, GET /api/v1/files/{file_id} is of Cn2data's FiVal API file-status endpoint.
Assertion
A signed statement from one system to another. In FiVal, the bearer assertion is a short-lived JWT in which a client asserts its identity, the represented user and tenant, the requested permissions, and the token's validity period.
Asynchronous processing
Work performed separately from the original HTTP request, often by a background worker. File hashing, validation, scanning, extraction, cleanup, and webhook delivery are suitable for asynchronous processing because they may take time or depend on external systems.
Audience
The intended recipient of a JWT, represented by its aud claim. FiVal requires this value to exactly match FIVAL_JWT_AUDIENCE. This prevents a token issued for another service from being reused with FiVal.
Audit event
An immutable record of an important action or state change. FiVal stores ordered AuditEvent records for each file so its lifecycle can be reviewed later.
Authentication
The process of proving who or what is making a request. FiVal authenticates clients by verifying RS256-signed JWT bearer assertions against registered RSA public keys.
Authorization
The process of deciding what an authenticated caller is allowed to do. FiVal authorizes a request by combining registered client permissions, token scopes, policy grants, and file ownership boundaries.
B
Background worker
A program or process that performs queued work outside the HTTP request-response cycle. of Cn2data's FiVal API future workers will verify uploads, validate files, scan for malware, extract content, and delete stored objects.
Bearer token
A credential sent in an HTTP Authorization header using the format Bearer TOKEN. Anyone possessing a valid bearer token may be able to use it until it expires, so clients must protect it and send it only over HTTPS.
Bulk write
A database operation that changes many records at once. Bulk writes can bypass normal model methods and lifecycle rules. of Cn2data's FiVal API ORM guards therefore restrict bulk changes to protected records.
C
Cache
Temporary storage used to reuse a previous response or computation. FiVal sends Cache-Control: no-store because file status and extracted content may be sensitive and should not be retained by browsers or intermediary caches.
Claim
A named fact inside a JWT payload. FiVal requires claims such as iss, aud, sub, tenant_id, iat, nbf, exp, jti, and scope.
Client application
A software system registered to call FiVal. A ClientApplication record contains the expected issuer, allowed scopes, active status, and public keys used to verify its signed assertions.
Clock skew
A small difference between the clocks of two computer systems. FiVal allows 30 seconds of clock skew when evaluating JWT time claims.
Concurrency
Two or more operations occurring during overlapping periods. FiVal uses transactions, row locks, expected states, and database uniqueness to stop concurrent requests from producing contradictory states or duplicate records.
Correlation ID
An identifier used to connect related logs or activities across components. Unlike an operation ID, a correlation ID may change between retries of the same logical command.
Cryptographic hash
A fixed-length value calculated from a file's bytes. If the file changes, its hash should change. FiVal binds validation evidence to the hash of the immutable snapshot that a worker actually examined.
curl
A command-line program for making HTTP requests. The implementation guide uses it to call FiVal endpoints and inspect response headers and bodies.
D
Database migration
A version-controlled change to a database schema or its required seed data. Django migrations create or modify tables consistently across development, testing, and production environments.
Database schema
The structure of a database, including its tables, columns, relationships, indexes, and constraints. of Cn2data's FiVal API 0001_initial migration creates its initial schema.
Database transaction
A group of database changes that succeed or fail as a unit. FiVal places a lifecycle state change, audit event, and outbox message in one transaction so it cannot commit only part of the operation.
Deletion receipt
Trusted evidence from the storage adapter that every required object version was removed and the upload capability expired or was revoked. An external upload request must never be permitted to supply a DeletionReceipt.
Dependency
An external software package required by a project. of Cn2data's FiVal API Python dependencies are installed from requirements.txt; PyJWT and its cryptography support are examples.
Dispatcher
A process that reads pending outbox messages, leases them, performs the requested external work, and records or retries the result. The future FiVal dispatcher must preserve immutable payloads and event IDs.
Django
A Python web framework that supplies URL routing, HTTP request handling, configuration, database models, migrations, testing tools, and other components used by FiVal.
Django Admin
Django's optional administrative website for authorized staff. Depending on the project configuration, it may be used to manage client registrations and policy grants. It should never be exposed as an unauthenticated registration mechanism.
Domain model
The application's representation of important business concepts and rules. of Cn2data's FiVal API domain model includes files, policies, validation attempts, results, extracted content, audit events, idempotency records, and outbox messages.
Domain service
Application code that performs operations while enforcing domain rules. FiVal views and workers should use services such as create_file, transition, record_check, record_scan, store_content, and read_content rather than modifying protected models directly.
E
Endpoint versioning
Including an API version in a URL or another request component so the API can evolve without unexpectedly breaking existing clients. FiVal currently uses /api/v1/.
Environment variable
A configuration value supplied outside the source code. FiVal uses FIVAL_JWT_AUDIENCE as an environment variable so each environment can define its expected token audience without hard-coding it.
Evidence
An immutable result showing what a trusted worker observed about a specific file snapshot. FiVal evidence is bound to a file hash, policy version, validation attempt, values, and timestamps.
Expected state
The lifecycle state that a caller believes a file is currently in. Every FiVal transition requires expected_state; the operation fails if another process has already moved the file to a different state.
Extracted content
Bounded text obtained from a validated file. FiVal stores it in ExtractedContent, separate from audit evidence, and releases it only through the domain service after ownership, approval, retention, and deletion checks.
F
File lifecycle
The controlled sequence of states through which a file passes. of Cn2data's FiVal API lifecycle includes creation, uploading, quarantine, validation, scanning, processing, approval or rejection, expiration, and deletion-related operations.
File record
The FileRecord model representing one managed file. It stores ownership, storage references, hash, pinned policy, current attempt, lifecycle state, retention, and deletion metadata.
Finite retention
A rule that keeps a record or content only for an allowed period. FiVal checks retention before releasing content and handles expiration separately from confirmed physical deletion.
H
HTTP
Hypertext Transfer Protocol, the standard request-response protocol used by web APIs. A request normally includes a method, URL, headers, and sometimes a body; the response includes a status code, headers, and a body.
HTTP header
A named piece of metadata attached to an HTTP request or response. FiVal uses the Authorization request header and returns headers such as Cache-Control and X-Request-ID.
HTTP method
A verb describing the requested action. GET requests data. Future FiVal operations may use methods such as POST for creation or commands, as defined by the implementation contract.
HTTP status code
A three-digit number summarizing the result of a request. FiVal uses codes including 404 for missing or inaccessible files, 409 for content that is not approved, and 410 for expired content.
HTTPS
HTTP protected by TLS encryption. Production bearer tokens and FiVal responses must travel over HTTPS to reduce the risk of interception or alteration.
I
Idempotency
The property that retrying the same logical request does not create duplicate effects. of Cn2data's FiVal API future create endpoint must use an IdempotencyRecord and create it in the same outer transaction as the file.
Idempotency key
A stable value supplied for a retryable request so the server can recognize repeated delivery. Its uniqueness must be scoped appropriately to prevent unrelated requests from being treated as duplicates.
Immutable
Not allowed to change after creation. FiVal makes policies and validation evidence immutable so later actions cannot silently rewrite what rules applied or what a worker observed.
Immutable snapshot
The exact, unchanging file object that a worker reads, hashes, scans, and validates. Using one snapshot prevents different checks from unknowingly examining different versions of a file.
Ingress
The trusted infrastructure entry point through which external traffic reaches an application. In production, FiVal should receive HTTPS traffic through its trusted ingress.
Issuer
The system that created and signed a JWT, represented by the iss claim. FiVal matches this value to an active ClientApplication registration.
J
JSON
JavaScript Object Notation, a common text format for structured API data. FiVal returns JSON for file status and errors, even though approved extracted content is returned as plain text.
JSON Web Token
A compact signed token, usually called a JWT, that carries claims between systems. FiVal accepts short-lived RS256 JWT bearer assertions with a fixed set of required claims.
jti
The JWT ID claim. It uniquely identifies a token and must be nonempty in FiVal assertions.
K
Key ID (kid)
A label, represented by kid in a JWT header, that tells FiVal which registered public key should verify the signature. It also allows old and new keys to overlap during rotation.
Key rotation
Replacing a cryptographic key in a controlled way. FiVal supports rotation by registering a new public key under a new kid, switching the client to the matching private key, waiting for old tokens to expire, and then removing the old public key.
L
Lease
A temporary claim by a worker or dispatcher that it is processing a queued item. Leasing helps prevent multiple workers from performing the same work simultaneously and allows another worker to retry after a failed or abandoned lease.
Least privilege
Granting only the permissions needed for a task. FiVal clients should receive only their necessary scopes and policy grants, and workers should be trusted only for their assigned responsibilities.
M
Malware scan
An examination of a file for malicious software. FiVal will store the scanner verdict and a derived validation check as immutable evidence for the current file snapshot and validation attempt.
Message broker
Infrastructure that delivers messages between applications or workers. FiVal must not publish to a broker while holding a database row lock; it first commits an outbox message and lets a dispatcher publish later.
Migration seed data
Required initial records installed by a database migration. FiVal migration 0002_joboy_resume_policy seeds the immutable joboy-resume version 1 policy but does not grant any client access to it.
Multi-tenant
An architecture in which one service supports multiple customer organizations while keeping their data separated. FiVal uses tenant_id, together with client and user identity, to enforce this separation.
O
Object storage
A storage system that manages files as objects, often with keys and multiple versions. of Cn2data's FiVal API storage adapter must remove every relevant object version during deletion and must not expose internal storage keys through the public API.
Operation ID
A stable UUID representing one logical lifecycle command. FiVal uses it to make redelivery safe. The same operation ID must not be reused for a different command.
ORM
Object-relational mapper. Django's ORM lets Python code work with database records as model objects. FiVal adds guards against ordinary saves, bulk writes, and deletes that would bypass lifecycle services.
Outbox message
A durable database record describing external work that must occur after a transaction commits. It prevents a state change from being saved without also preserving the intent to notify a worker or deliver a webhook.
Outbox pattern
A reliability technique in which an application writes business changes and an outgoing message to the same database transaction. A separate dispatcher later delivers the message, avoiding unsafe network calls inside the transaction.
P
Parsing
Reading a file's structure and converting it into usable data or text. FiVal does not yet perform parsing; a future content-extraction worker will do so under strict trust and size limits.
PEM
A text encoding commonly used for cryptographic keys. FiVal stores each registered RSA public key as PEM text beginning with a marker such as —--BEGIN PUBLIC KEY—--.
Permission scope
A named API permission. FiVal uses scopes such as files:read and files:content. Effective permissions are limited to the intersection of scopes in the token and scopes registered for the client.
Policy grant
A PolicyGrant record authorizing a client application to use a particular policy version. The seeded joboy-resume policy does not grant access until this relationship is created.
Policy version
An immutable set of validation and retention rules identified by a name and version number. Pinning a file to a PolicyVersion preserves exactly which rules governed its processing.
PostgreSQL
The relational database used for complete FiVal testing and production-style behavior. Unlike the isolated SQLite setup, PostgreSQL can test the row-locking and concurrency guarantees on which the lifecycle depends.
Private key
The secret half of an asymmetric cryptographic key pair. A client uses its RSA private key to sign JWTs. FiVal must never store that private key.
Public key
The nonsecret half of an asymmetric key pair. FiVal stores a client's RSA public key and uses it to verify signatures produced with the matching private key.
PyJWT
A Python library for encoding and decoding JWTs. FiVal uses PyJWT with cryptography support, a fixed RS256 algorithm, and explicitly required claims.
Q
Quarantine
A restricted lifecycle state for an uploaded file that has been verified as an immutable snapshot but has not yet passed validation and malware scanning. Quarantined content must not be released to users.
R
Race condition
A defect in which the result depends on the timing of concurrent operations. FiVal reduces race conditions with row locks, transactions, uniqueness constraints, expected states, operation IDs, and attempt IDs.
Request ID
A server-generated identifier for one HTTP request. FiVal includes it in the error body and the X-Request-ID response header so operators can correlate a client-visible error with server logs.
Response body
The data returned by an HTTP endpoint. FiVal status and error bodies use JSON; approved extracted content uses plain text.
Retention policy
Rules defining how long records, files, or extracted content may be kept. FiVal checks retention during access and requires separate controlled implementations for cleanup and administrative purging.
Retry
A repeated attempt after an operational failure. retry_file creates a new validation attempt, reruns all checks, invalidates old attempt IDs, and does not extend failed-file retention.
Row lock
A database lock that temporarily prevents conflicting operations on the same record. FiVal locks the file row while applying lifecycle changes and when deciding whether content may be released.
RSA
An asymmetric cryptographic system that uses a private key for signing and a public key for verification. FiVal requires registered RSA public keys of at least 2048 bits.
RS256
A JWT signature algorithm using RSA with SHA-256. FiVal explicitly allows this algorithm rather than trusting an algorithm named by an unverified token.
S
Scope intersection
The permissions common to both the token's requested scopes and the registered client's allowed scopes. FiVal uses this intersection as the caller's effective permissions.
Snapshot
Trusted metadata describing the exact immutable stored file that a worker verified and hashed. A client upload request must never be allowed to manufacture or submit a trusted Snapshot.
Stale work
Queued work that refers to an older validation attempt after a retry created a new one. FiVal includes an attempt ID in work payloads so consumers can detect and reject stale work.
State transition
A controlled change from one lifecycle state to another. FiVal performs transitions through its domain service and checks the expected state, actor, operation ID, current attempt, and required evidence.
Storage capability
A limited credential or signed permission allowing a client to upload to a specific storage location. of Cn2data's FiVal API future storage adapter will issue these capabilities and must ensure they expire or are revoked before deletion is confirmed.
Subject
The identity represented by the sub claim in a JWT. In FiVal, it identifies the user on whose behalf the registered client is making the request.
T
Tenant
A customer organization or isolated account within a shared system. FiVal uses the verified tenant_id claim to ensure one tenant cannot access another tenant's files.
Test database
A separate database created for automated tests. It protects real development and production data and allows tests to create, change, and delete records freely. of Cn2data's FiVal API PostgreSQL user needs permission to create it.
TLS
Transport Layer Security, the encryption and server-authentication technology used by HTTPS. FiVal production requests should pass through trusted TLS-enabled ingress.
Token expiration
The time after which a token is invalid, represented by the exp claim. FiVal tokens may have a lifetime of no more than five minutes.
Transaction boundary
The exact set of actions included in one database transaction. FiVal includes state, audit, and outbox writes inside the boundary but keeps broker publishing and storage network calls outside it.
Trust boundary
The point where untrusted external data enters a trusted component. FiVal treats HTTP input, uploaded files, and extracted content as untrusted and permits only authenticated adapters and trusted workers to construct certain internal evidence.
U
Uniqueness constraint
A database rule preventing duplicate values within a defined scope. The future FiVal create endpoint must handle concurrent violations of the idempotency-record uniqueness constraint safely.
Untrusted content
Data that must not be treated as instructions or executable code. FiVal labels extracted text untrusted: true; downstream systems must display or process it safely.
URL
A Uniform Resource Locator identifying an API resource or action. FiVal uses versioned paths such as /api/v1/files/{file_id}.
UUID
A universally unique identifier. FiVal requires a stable UUID as the operation_id for each logical lifecycle command.
V
Validation attempt
One complete run of required checks against a specific immutable file snapshot and policy version. Each retry creates a new ValidationAttempt; evidence from an older attempt cannot approve the new one.
Validation check
A recorded result for one requirement in a policy, such as a preliminary file check, malware check, or extraction check. Approval requires all current-attempt requirements to pass.
Validation result
Immutable evidence recorded in ValidationResult for a check performed during a validation attempt.
Virtual environment
An isolated Python environment containing the packages required by one project. Activating it helps ensure FiVal uses the intended Python interpreter and dependency versions.
W
Webhook
An HTTP notification sent by one system to another when an event occurs. of Cn2data's FiVal API future webhook delivery should use durable outbox messages, stable event IDs, retries, and receiver-side deduplication.
Worker attempt ID
The validation-attempt identifier included with background work and evidence. A worker must submit the current ID so FiVal can reject results from an earlier, superseded attempt.
Symbols and FiVal settings
aud
The JWT audience claim. It must be a string exactly equal to FIVAL_JWT_AUDIENCE.
exp
The JWT expiration-time claim, expressed as an integer timestamp.
FIVAL_JWT_AUDIENCE
The environment setting defining the only valid JWT audience for FiVal. An empty value causes authentication to be denied.
iat
The JWT issued-at claim, expressed as an integer timestamp.
iss
The JWT issuer claim. It must match an active registered client application.
kid
The key ID in the JWT header. It selects the registered public key FiVal uses for signature verification.
nbf
The JWT not-before claim. It specifies the earliest time at which the token may be accepted.
scope
The JWT claim containing requested permissions as a space-delimited string, such as files:read files:content.
sub
The JWT subject claim identifying the represented user.
tenant_id
The required JWT claim identifying the tenant whose data the request may access.
X-Request-ID
The response header containing of Cn2data's FiVal API server-generated request identifier.