{"id":31642011,"url":"https://github.com/startcloud/armor","last_synced_at":"2026-04-22T08:01:07.006Z","repository":{"id":317460737,"uuid":"1062159847","full_name":"STARTcloud/armor","owner":"STARTcloud","description":"ARMOR Reliably Manages Online Resources","archived":false,"fork":false,"pushed_at":"2026-04-22T03:03:15.000Z","size":2709,"stargazers_count":0,"open_issues_count":19,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T03:12:23.074Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/STARTcloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":"audit-ci.jsonc","citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T22:18:55.000Z","updated_at":"2026-04-22T03:00:56.000Z","dependencies_parsed_at":"2025-10-01T03:22:48.724Z","dependency_job_id":null,"html_url":"https://github.com/STARTcloud/armor","commit_stats":null,"previous_names":["startcloud/armor"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/STARTcloud/armor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STARTcloud%2Farmor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STARTcloud%2Farmor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STARTcloud%2Farmor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STARTcloud%2Farmor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/STARTcloud","download_url":"https://codeload.github.com/STARTcloud/armor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STARTcloud%2Farmor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32126709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T07:37:52.372Z","status":"ssl_error","status_checked_at":"2026-04-22T07:37:51.635Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-07T03:28:32.013Z","updated_at":"2026-04-22T08:01:06.997Z","avatar_url":"https://github.com/STARTcloud.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Armor\r\n\r\n**ARMOR Reliably Manages Online Resources**\r\n\r\nA secure Node.js file server that provides directory listings with SHA256 checksums and authenticated file upload capabilities over HTTPS.\r\n\r\n## Features\r\n\r\n- Secure HTTPS access\r\n- Basic authentication for uploads\r\n- Clean, dark-themed directory listings\r\n- SHA256 checksums for all files\r\n  - Truncated display with full checksum in tooltip\r\n  - Click-to-copy functionality\r\n  - Visual confirmation when copied\r\n- File upload support (authenticated users only)\r\n  - Drag-and-drop enabled\r\n  - Automatic checksum calculation on upload\r\n- Nested directory support\r\n- File size formatting\r\n- Automatic directory creation on upload\r\n\r\n## Installation\r\n\r\n### Prerequisites\r\n\r\n1. Install Node.js on Debian 12:\r\n```bash\r\ncurl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -\r\nsudo apt-get install -y nodejs\r\n```\r\n\r\n### Application Setup\r\n\r\n1. Create application directory and set permissions:\r\n```bash\r\nsudo mkdir -p /opt/armor\r\nsudo chown startcloud:startcloud /opt/armor\r\n```\r\n\r\n2. Create data directory:\r\n```bash\r\nsudo mkdir -p /local/www\r\nsudo chown startcloud:startcloud /local/www\r\n```\r\n\r\n3. Copy application files:\r\n```bash\r\nsudo cp app.js package.json config.yaml /opt/armor/\r\nsudo chown startcloud:startcloud /opt/armor/*\r\n```\r\n\r\n4. Install dependencies:\r\n```bash\r\ncd /opt/armor\r\nnpm install\r\n```\r\n\r\n### Authentication Setup\r\n\r\nThe application uses a YAML file for user authentication. Edit config.yaml to manage users:\r\n```yaml\r\nusers:\r\n  - username: admin\r\n    password: your-secure-password\r\n  - username: user2\r\n    password: another-password\r\n```\r\n\r\n### SSL Certificates\r\n\r\nThe application uses SSL certificates from Let's Encrypt located at:\r\n- `/etc/letsencrypt/live/armor.mydomain.net/fullchain.pem`\r\n- `/etc/letsencrypt/live/armor.mydomain.net/privkey.pem`\r\n\r\nEnsure these certificates are readable by the startcloud user:\r\n```bash\r\nsudo setfacl -R -m u:startcloud:rx /etc/letsencrypt/live/armor.mydomain.net/\r\nsudo setfacl -R -m u:startcloud:rx /etc/letsencrypt/archive/armor.mydomain.net/\r\n```\r\n\r\n### Service Setup\r\n\r\n1. Copy service file:\r\n```bash\r\nsudo cp armor.service /etc/systemd/system/\r\n```\r\n\r\n2. Enable and start the service:\r\n```bash\r\nsudo systemctl daemon-reload\r\nsudo systemctl enable armor\r\nsudo systemctl start armor\r\n```\r\n\r\n## Usage\r\n\r\n1. Access the server at `https://armor.mydomain.net`\r\n\r\n2. Authentication:\r\n   - Click the \"Login to Upload\" button in the top-right corner\r\n   - Enter your credentials from config.yaml when prompted\r\n   - Once logged in, you'll see a \"Logged in\" indicator\r\n   - The upload form will appear automatically\r\n\r\n3. Directory Navigation:\r\n   - Click folders to navigate into them\r\n   - Use the \"Back\" button to return to parent directory\r\n   - File paths are shown in the page header\r\n\r\n4. File Operations:\r\n   - Click on a file name to download it\r\n   - Authenticated users can upload files using the upload form or drag-and-drop\r\n   - Files are automatically saved to the current directory\r\n   - Checksums are calculated automatically on upload\r\n\r\n5. Checksum Features:\r\n   - Checksums are displayed in truncated form (first 8 characters)\r\n   - Hover over a checksum to see the full value\r\n   - Click a checksum to copy it to clipboard\r\n   - A green notification appears when copied successfully\r\n\r\n## Service Management\r\n\r\n- Check service status:\r\n```bash\r\nsudo systemctl status armor\r\n```\r\n\r\n- View logs:\r\n```bash\r\nsudo journalctl -u armor\r\n```\r\n\r\n- Restart service:\r\n```bash\r\nsudo systemctl restart armor\r\n```\r\n\r\n## Troubleshooting\r\n\r\n1. If the service fails to start:\r\n   - Check logs: `sudo journalctl -u armor -n 50`\r\n   - Verify Node.js installation: `node --version`\r\n   - Check SSL certificate permissions\r\n   - Verify file permissions in /local/www\r\n   - Ensure startcloud user has necessary permissions\r\n\r\n2. If file uploads fail:\r\n   - Verify you are properly authenticated\r\n   - Check directory permissions for startcloud user\r\n   - Check available disk space\r\n   - Ensure the service is running\r\n\r\n3. If checksums don't appear:\r\n   - Verify file permissions allow reading\r\n   - Check service logs for errors\r\n   - Ensure file is not corrupted\r\n\r\n4. If authentication fails:\r\n   - Verify config.yaml is properly formatted\r\n   - Check config.yaml permissions\r\n   - Ensure credentials are correct\r\n   - Check service logs for auth-related errors\r\n   - Try clearing browser cache and cookies\r\n   - Ensure you're using the correct username/password from config.yaml\r\n\r\n## API Documentation\r\n\r\nThe application provides a comprehensive REST API documented with Swagger UI. Access the interactive documentation at:\r\n```\r\nhttps://your-domain.com/api-docs\r\n```\r\n\r\n### API Authentication\r\n\r\nThe API supports two authentication methods:\r\n1. **API Keys** - Bearer token authentication (recommended for programmatic access)\r\n2. **JWT Tokens** - Session-based authentication (for web interface)\r\n\r\n### API Key Management\r\n\r\nCreate and manage API keys through the web interface at `/api-keys` or via the API:\r\n\r\n```bash\r\n# List your API keys\r\ncurl -k -H \"Authorization: Bearer YOUR_API_KEY\" \\\r\n  https://your-domain.com/api/api-keys\r\n\r\n# Create new API key\r\ncurl -k -X POST -H \"Authorization: Bearer YOUR_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\"name\":\"My App\",\"permissions\":[\"downloads\",\"uploads\",\"delete\"],\"expires_at\":\"2025-12-31T23:59:59.000Z\"}' \\\r\n  https://your-domain.com/api/api-keys\r\n```\r\n\r\n### API Endpoints\r\n\r\n#### 🔑 API Keys\r\n- `GET /api/api-keys` - List user's API keys\r\n- `POST /api/api-keys` - Create new API key\r\n- `PUT /api/api-keys/{id}` - Update API key\r\n- `DELETE /api/api-keys/{id}` - Delete API key\r\n\r\n#### 📁 Files\r\n- `GET /{path}` - Download file or list directory (JSON with Accept: application/json)\r\n- `POST /{path}` - Upload file (multipart/form-data)\r\n- `POST /{path}?action=create-folder` - Create folder\r\n- `DELETE /{path}` - Delete file or directory\r\n\r\n#### 🔍 Search\r\n- `POST /{path}?action=search` - Search files by name or checksum\r\n\r\n#### 🔐 Authentication\r\n- `GET /auth/methods` - Get available authentication methods\r\n- `POST /auth/login/basic` - Basic username/password login\r\n- `POST /auth/logout` - Logout and clear token\r\n\r\n### API Examples\r\n\r\n**Note**: Use `-k` flag with curl for self-signed certificates.\r\n\r\n#### File Operations\r\n```bash\r\n# List directory contents (JSON)\r\ncurl -k -H \"Authorization: Bearer YOUR_API_KEY\" \\\r\n  -H \"Accept: application/json\" \\\r\n  https://your-domain.com/uploads/\r\n\r\n# Download a file\r\ncurl -k -H \"Authorization: Bearer YOUR_API_KEY\" \\\r\n  --output filename.ext \\\r\n  https://your-domain.com/uploads/filename.ext\r\n\r\n# Upload file to specific directory\r\ncurl -k -X POST -H \"Authorization: Bearer YOUR_API_KEY\" \\\r\n  -F \"file=@./local-file.txt\" \\\r\n  https://your-domain.com/uploads/documents/\r\n\r\n# Create folder (clean dedicated endpoint)\r\ncurl -k -X POST -H \"Authorization: Bearer YOUR_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\"folderName\":\"new-folder\"}' \\\r\n  https://your-domain.com/uploads/folders\r\n\r\n# Rename file or folder\r\ncurl -k -X PUT -H \"Authorization: Bearer YOUR_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\"newName\":\"new-filename.txt\"}' \\\r\n  https://your-domain.com/uploads/oldname.txt?action=rename\r\n\r\n# Delete file or folder\r\ncurl -k -X DELETE -H \"Authorization: Bearer YOUR_API_KEY\" \\\r\n  https://your-domain.com/uploads/filename.ext\r\n```\r\n\r\n#### Search Operations\r\n```bash\r\n# Search for files by name or checksum (clean dedicated endpoint)\r\ncurl -k -X POST -H \"Authorization: Bearer YOUR_API_KEY\" \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\"query\":\"document\"}' \\\r\n  https://your-domain.com/uploads/search\r\n```\r\n\r\n#### Authentication\r\n```bash\r\n# Get available authentication methods\r\ncurl -k https://your-domain.com/auth/methods\r\n\r\n# Login with username/password\r\ncurl -k -X POST -H \"Content-Type: application/json\" \\\r\n  -d '{\"username\":\"admin\",\"password\":\"your-password\"}' \\\r\n  https://your-domain.com/auth/login/basic\r\n```\r\n\r\n### API Key Permissions\r\n\r\nAPI keys can have the following permissions:\r\n- **downloads** - Access to download files and list directories\r\n- **uploads** - Access to upload files and create folders\r\n- **delete** - Access to delete files and directories\r\n\r\n### Swagger UI Features\r\n\r\nThe interactive API documentation includes:\r\n- **Dark theme** - Professional dark UI\r\n- **Dynamic server configuration** - Auto-detects current server with custom override\r\n- **API key integration** - Seamless authentication in the browser\r\n- **Temporary key generation** - On-demand testing keys\r\n- **Profile navigation** - Easy access to key management\r\n\r\n## Notes\r\n\r\n- The server runs on port 443 (HTTPS)\r\n- Files are stored in /local/www\r\n- Service runs as startcloud user and group\r\n- Nested directories are created automatically when needed\r\n- File names are sanitized during upload\r\n- Hidden files and system files are excluded from listings\r\n- All connections are secured with SSL/TLS\r\n- Authentication is required only for file uploads\r\n- API endpoints require appropriate permissions based on operation type\r\n- Path in URL determines target directory for file operations\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstartcloud%2Farmor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstartcloud%2Farmor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstartcloud%2Farmor/lists"}