https://github.com/wuespace/deno-asn-generator
A Deno based system for generating / managing ASNs for documentat management systems in a collaborative environment.
https://github.com/wuespace/deno-asn-generator
asn cli deno dms docker document-management numbering numbering-system reference-number web
Last synced: 2 months ago
JSON representation
A Deno based system for generating / managing ASNs for documentat management systems in a collaborative environment.
- Host: GitHub
- URL: https://github.com/wuespace/deno-asn-generator
- Owner: wuespace
- License: mit
- Created: 2024-09-06T12:46:48.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-12-12T14:02:07.000Z (6 months ago)
- Last Synced: 2025-04-10T22:54:16.285Z (2 months ago)
- Topics: asn, cli, deno, dms, docker, document-management, numbering, numbering-system, reference-number, web
- Language: TypeScript
- Homepage:
- Size: 434 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Deno ASN Generator
[](https://jsr.io/@wuespace)
[](https://jsr.io/@wuespace/asn-generator)
[](https://jsr.io/badges/@wuespace/asn-generator/score)
[](https://github.com/wuespace/deno-asn-generator/actions/workflows/deno-ci.yml)
[](https://github.com/wuespace/deno-asn-generator/actions/workflows/docker-publish.yml)
[Deployment](DEPLOY.md) ·
[Configuration](env.md) ·
[License (MIT)](./LICENSE) ·
[Contributing](./CONTRIBUTING.md)
---
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](./ASN_FORMAT_EXAMPLES.md) for a list of examples with
> different configurations.
```text
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
- [x] Configurability through environment variables
- [x] Log generated ASNs to the file system
- [x] Connection to a database
- [x] REST API
- [x] Visual Web Interface
- [x] CLI
- [x] Bump counter to avoid collissions after restoring backups (where ASNs
could have been generated after the time of the backup)
- [x] 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
- [x] Documentation
- [x] Publish on JSR
- [ ] Publish on Docker Hub
- [x] Publish on GitHub Container Registry
- [x] UI for quickly searching for ASNs in a DMS