Deno ASN Generator

Deployment · License (MIT) · Contributing

---

An environment for collaboratively creating ASN numbers to be used in the Paperless-NGX based document management system at WüSpace e. V.

Screenshot of the Web UI.

Application Logo.

Core Requirements

• REQ-1: The system must be able to generate unique ASN numbers.
• REQ-2: The system must be able to be used by multiple users at the same time.
• REQ-3: The system must allow reserving a range of ASNs for manual assignment (e.g., for pre-printed barcodes).
• REQ-4: The system must be able to be configured to use a specific prefix for the ASN numbers.
• REQ-5: The system must be easy to deploy and maintain.

Concept / ASN Format

Note

The exact format of the ASN is configurable through environment variables. See ASN_FORMAT_EXAMPLES.md for a list of examples with different configurations.

WUE  - 100  - 001
(1)  - (2)  - (3)

(1) Prefix specified in configuration (WUE).
(2) Numeric Namespace, whereas
    - 100-599 is reserved for automatic generation, and
    - 600-999 is reserved for user defined namespaces.
    The user defined namespace can be used for pre-printed ASN barcodes and the like.
(3) Counter, starting from 001, incrementing with each new ASN in the namespace.

Calculation of the Namespace

For this example, we'll define $100$ to $599$ as the automatic namespace and $600$ to $999$ as the user defined namespace. We notate this as

$$ r:=600 $$

Note that the minimum and maximum overall namespace values $r_{min}$ and $r_{max}$ can be derived as they have to be the minimum and maximum numeric values with the same number of digits as $r$ to avoid collisions.

Furthermore, let $t$ be the number of milliseconds since the Unix epoch. We can calculate the current namespace $n$ as follows:

$$ n \in [r_{min}, r]; n = r_{min} + t \mod (r - r_{min}) $$

OpenID Connect / Authentication

The system can optionally be configured to use OpenID Connect for authentication. In this case, only authenticated users can generate ASNs. Read-only and lookup routes will still be available to all users.

OpenID Connect is enabled when the OIDC_ISSUER environment variable is set.

To configure the system to use OpenID Connect, set the following environment variables:

• OIDC_ISSUER: The issuer URL of the OpenID Connect provider.
• OIDC_CLIENT_ID: The client ID of the application.
• OIDC_CLIENT_SECRET: The client secret of the application.
• OIDC_REDIRECT_URI: The redirect URI of the application (https://your-domain/oidc/callback).
• OIDC_SCOPES: The scopes to request from the OpenID Connect provider.
• OIDC_AUTH_SECRET: A secret used to sign the session cookie. Must be at least 32 characters long.

Optionally, you can set the following environment variables:

• OIDC_UID_CLAIM: The claim in the ID token that contains the user's unique identifier. Defaults to sub.
• OIDC_NAME_CLAIM: The claim in the ID token that contains the user's name. Defaults to name.
• OIDC_ROLES_CLAIM: The claim in the ID token that contains the user's roles. Defaults to groups. While roles are currently not used by the generator, they may in the future be used for RBAC.

Ideas / Roadmap

• Configurability through environment variables
• Log generated ASNs to the file system
• Connection to a database
• REST API
• Visual Web Interface
• CLI
  • Bump counter to avoid collissions after restoring backups (where ASNs could have been generated after the time of the backup)
  • Analyze time between ASNs, providing the possibility to specify a duration and a maximum collision probability for the bump (e.g. 1 hour, 0.1%), which calculates the bump counter accordingly
• Documentation
• Publish on JSR
• Publish on Docker Hub
• Publish on GitHub Container Registry
• UI for quickly searching for ASNs in a DMS