{"id":17651744,"url":"https://github.com/diegovictor/mail-authorizer","last_synced_at":"2025-04-14T18:54:22.245Z","repository":{"id":253396992,"uuid":"843075706","full_name":"DiegoVictor/mail-authorizer","owner":"DiegoVictor","description":"API that uses a custom AWS Lambda as authorizer for other Lambdas. It uses a TOTP code sent to users' email to generate a JWT that allow them to get a signed URL for a given file.","archived":false,"fork":false,"pushed_at":"2025-02-22T14:28:46.000Z","size":36734,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T07:22:18.124Z","etag":null,"topics":["authorization","authorizer","aws","cloudfront","dynamodb","javascript","js","jwt","mail-authorizer","node","nodejs","s3","serverless","serverless-framework","ses","totp","ts","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DiegoVictor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-15T18:20:46.000Z","updated_at":"2025-02-22T14:28:49.000Z","dependencies_parsed_at":"2025-02-22T15:41:56.274Z","dependency_job_id":null,"html_url":"https://github.com/DiegoVictor/mail-authorizer","commit_stats":null,"previous_names":["diegovictor/mail-authorizer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiegoVictor%2Fmail-authorizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiegoVictor%2Fmail-authorizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiegoVictor%2Fmail-authorizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DiegoVictor%2Fmail-authorizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DiegoVictor","download_url":"https://codeload.github.com/DiegoVictor/mail-authorizer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248942383,"owners_count":21186942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["authorization","authorizer","aws","cloudfront","dynamodb","javascript","js","jwt","mail-authorizer","node","nodejs","s3","serverless","serverless-framework","ses","totp","ts","typescript"],"created_at":"2024-10-23T11:43:28.788Z","updated_at":"2025-04-14T18:54:22.238Z","avatar_url":"https://github.com/DiegoVictor.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mail Authorizer\n[![AppVeyor](https://img.shields.io/appveyor/build/diegovictor/mail-authorizer?logo=appveyor\u0026style=flat-square)](https://ci.appveyor.com/project/DiegoVictor/mail-authorizer)\n[![dynamodb](https://img.shields.io/badge/dynamodb-3.624.0-4053D6?style=flat-square\u0026logo=amazondynamodb)](https://aws.amazon.com/dynamodb)\n[![serverless](https://img.shields.io/badge/serverless-3.40.0-FD5750?style=flat-square\u0026logo=serverless)](https://www.serverless.com/)\n[![typescript](https://img.shields.io/badge/typescript-4.9.5-3178c6?style=flat-square\u0026logo=typescript)](https://www.typescriptlang.org/)\n[![babel](https://img.shields.io/badge/babel-7.25.2-F9DC3E?style=flat-square\u0026logo=babel)](https://babeljs.io/)\n[![jest](https://img.shields.io/badge/jest-29.7.0-brightgreen?style=flat-square\u0026logo=jest)](https://jestjs.io/)\n[![coverage](https://img.shields.io/codecov/c/gh/DiegoVictor/mail-authorizer?logo=codecov\u0026style=flat-square)](https://codecov.io/gh/DiegoVictor/mail-authorizer)\n[![MIT License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](https://raw.githubusercontent.com/DiegoVictor/mail-authorizer/refs/heads/main/LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n\nIt allows users to authenticate using email address and an OTP code sent through email message and once authenticated you can download files content and upload new files. It also has a trigger for new uploaded files that adds the file to AWS DynamoDB and make it is listed in the endpoints. CloudFront was used to caching files.\n\n![Infrastructure Diagram](https://raw.githubusercontent.com/DiegoVictor/mail-authorizer/refs/heads/main/MailAuthorizer.drawio.png)\n\n## Table of Contents\n* [Requirements](#requirements)\n* [Install](#install)\n  * [.env](#env)\n* [Usage](#usage)\n  * [Routes](#routes)\n    * [Requests](#requests)\n* [Deploy](#deploy)\n* [Running the tests](#running-the-tests)\n  * [Coverage report](#coverage-report)\n\n# Requirements\n* Node.js ^20.16.0\n* Serveless Framework\n* AWS Account\n  * [S3](https://aws.amazon.com/s3)\n  * [Lambda](https://aws.amazon.com/lambda)\n  * [API Gateway](https://aws.amazon.com/api-gateway)\n  * [DynamoDB](https://aws.amazon.com/dynamodb)\n  * [SES](https://aws.amazon.com/pt/ses)\n  * [CloudFront](https://aws.amazon.com/pt/cloudfront)\n  * [Secrets Manager](https://aws.amazon.com/pt/secrets-manager)\n\n# Install\n```\nnpm install\n```\nOr:\n```\nyarn\n```\n\n## .env\nRename the `.env.example` in the root directory to `.env` then update it with your settings.\n\n|key|description\n|---|---\n|TOTP_KEY|An alphanumeric random string. Seed used to generate OTP codes. Base32 string, ie. only containing characters matching (A-Z, 2-7, =).\n|JWT_SECRET|An alphanumeric random string. Used to create signed tokens.\n|NOREPLY_EMAIL_ADDRESS|Email address used to send the OTP code email message.\n|REGION|AWS Region.\n\n# Usage\nFirst you will need to generate public and private keys for CloudFront Distribution:\n\n```shell\nopenssl genpkey -algorithm RSA -out private_key.pem\nopenssl rsa -pubout -in private_key.pem -out public_key.pem\n```\n\u003e Once the files exist they will be included into the package by `serverless.ts` configuration file during deployment too.\n\nNow we need to spin up localstack container and create the needed resources using `localstack.sh` script:\n```shell\ndocker-compose up -d\ndocker-compose exec -it localstack sh -c \"/var/lib/localstack/scripts/localstack.sh\"\n```\n\u003e Or you can access the container and run `sh /var/lib/localstack/scripts/localstack.sh`.\n\nNow start the server:\n```shell\nyarn dev:server\n```\nOr:\n```shell\nnpm run dev:server\n```\n\n## Routes\n|route|HTTP Method|params|description|authentication\n|:---|:---:|:---:|:---:|:---:\n|`/files`|GET|`cursorId` query parameter.|List files.| -\n|`/files/:id/signed-url`|GET|`id` of a file.|Generate a signed URL to download file content.|Required\n|`/files`|POST|Body with `title` and `filename`.|Generate presigned URL to upload file.|Required\n|`/auth`|POST|Body with `email`.|Send OTP code to the provided email address.| -\n|`/auth`|POST|Body with `email` and `otp`.|Authenticate user and generate JWT token.| -\n\n### Requests\n\n* `POST /files`\n\nRequest body:\n```json\n{\n    \"title\": \"Lorem Ipsum\",\n    \"filename\": \"sample.mp4\"\n}\n```\n\n* `POST /auth`\n\nRequest body:\n```json\n{\n    \"email\": \"johndoe@example.com\"\n}\n```\n\n```json\n{\n    \"email\": \"johndoe@example.com\",\n    \"otp\": \"111065\"\n}\n```\n\n# Deploy\nActually you are ready to deploy:\n```shell\nsls deploy\n```\n\n# Running the tests\n[Jest](https://jestjs.io/) was the choice to test the app, to run:\n```\n$ yarn test\n```\nOr:\n```\n$ npm run test\n```\n\u003e Run the command in the root folder\n\n## Coverage report\nYou can see the coverage report inside `tests/coverage`. They are automatically created after the tests run.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiegovictor%2Fmail-authorizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiegovictor%2Fmail-authorizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiegovictor%2Fmail-authorizer/lists"}