{"id":51851827,"url":"https://github.com/de-otio/saas-foundation","last_synced_at":"2026-07-23T20:31:00.960Z","repository":{"id":364818392,"uuid":"1255069100","full_name":"de-otio/saas-foundation","owner":"de-otio","description":"Runtime and AWS CDK foundation for de-otio multi-tenant SaaS backends: magic-link identity (vestibulum), tenant isolation, and deployment plumbing. Four published npm packages.","archived":false,"fork":false,"pushed_at":"2026-07-21T05:49:58.000Z","size":1933,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-21T07:17:44.475Z","etag":null,"topics":["aws","aws-cdk","cloudfront","cognito","magic-link","monorepo","multi-tenancy","oidc","saas","serverless","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/de-otio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T11:13:46.000Z","updated_at":"2026-07-21T05:43:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/de-otio/saas-foundation","commit_stats":null,"previous_names":["de-otio/saas-foundation"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/de-otio/saas-foundation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/de-otio%2Fsaas-foundation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/de-otio%2Fsaas-foundation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/de-otio%2Fsaas-foundation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/de-otio%2Fsaas-foundation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/de-otio","download_url":"https://codeload.github.com/de-otio/saas-foundation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/de-otio%2Fsaas-foundation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35816503,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["aws","aws-cdk","cloudfront","cognito","magic-link","monorepo","multi-tenancy","oidc","saas","serverless","typescript"],"created_at":"2026-07-23T20:31:00.341Z","updated_at":"2026-07-23T20:31:00.955Z","avatar_url":"https://github.com/de-otio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# saas-foundation\n\n[![CI](https://github.com/de-otio/saas-foundation/actions/workflows/ci.yml/badge.svg)](https://github.com/de-otio/saas-foundation/actions/workflows/ci.yml)\n\nThe runtime and infrastructure tier underneath every multi-tenant\nSaaS backend built in the de-otio house. A monorepo of four\npublished packages chosen because each one gets re-typed by hand\nevery time a new backend starts.\n\n\u003e **Published for inspection, not for contributions.** This repository\n\u003e is public so its design and code can be read, learned from, forked,\n\u003e and reused under the [license](LICENSE). It is **not** currently\n\u003e accepting external pull requests or issue reports — the author\n\u003e maintains it on a best-effort basis under time constraints. See\n\u003e [`CONTRIBUTING.md`](CONTRIBUTING.md) for what that means in practice.\n\n## Status\n\n**Implemented.** All four packages are built, typecheck across the\nproject-reference graph, and pass their test suites; the\nshared-distribution (shared CloudFront + shared Cognito pool) feature\nis implemented in `vestibulum` and `vestibulum-cdk`. See\n[`doc/12-remaining-work.md`](doc/12-remaining-work.md) for outstanding\nitems before publish. The design went through four design-review\npasses (full-set, foundation-cdk + AWS-fact verification,\nshared-distribution, and AWS Well-Architected cost pillar); their\nfindings have been folded into the design docs and the shipped code.\n\nThe Roman-house naming convention: the *foundation* is the slab the\nhouse sits on; *vestibulum* is the entrance hall inside it. They\nshare a monorepo because the contact surface between them\n(`TenantId`, `AuditEvent`, `SecretRef`, the claim-resolver\ncallbacks) is tighter than two separate release pipelines could\nkeep in sync.\n\n## The four packages\n\n| Package                            | Role                                                                                                                                                                                          | Optional? |\n|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|\n| **`@de-otio/saas-foundation`**     | Runtime core: cloud-primitive shims (`kv`, `queue`, `storage`), secrets, session crypto, tenant context, audit, structured logger, rate-limit, region/residency, feature toggles, IP derivation. No identity opinions. | required for any consumer |\n| **`@de-otio/vestibulum`**          | Identity runtime: Cognito IdP managers (OIDC + SAML), multi-pool JWT verifier, Cognito Lambda trigger templates, OIDC issuer probe with SSRF defence, SAML metadata parser, and the shared-distribution edge / trigger / admin handlers. Cognito-shaped.   | optional — only for consumers using Cognito |\n| **`@de-otio/saas-foundation-cdk`** | AWS CDK constructs for deployment plumbing every house backend needs: `NodejsLambda`, `QueueWithDlq`, `SingleTable`, house CloudWatch dashboard templates. Identity-agnostic.                  | optional — install when you want the house defaults |\n| **`@de-otio/vestibulum-cdk`**      | CDK constructs for opinionated passwordless magic-link auth on Cognito `CUSTOM_AUTH` with CloudFront edge auth via Lambda@Edge (EU-residency), in two flavours: single-tenant (`MagicLinkIdentity` / `MagicLinkAuthSite`) and shared-pool multi-tenant (`SharedDistributionIdentity`).                            | optional — only for consumers wanting this topology |\n\nA consumer who wants only the runtime cloud primitives installs\n`@de-otio/saas-foundation`. A consumer with Cognito + their own CDK\ninstalls `@de-otio/saas-foundation` + `@de-otio/vestibulum`. A\nconsumer who wants the canonical magic-link site installs the\nruntime pair plus both CDK packages — `MagicLinkAuthSite` for a\nsingle tenant, or `SharedDistributionIdentity` to serve many tenants\nbehind one CloudFront distribution with data-only onboarding. A\nconsumer who wants generic\nAWS plumbing (Lambdas, queues, tables, dashboards) but rolls their\nown auth installs `@de-otio/saas-foundation` +\n`@de-otio/saas-foundation-cdk`. See\n[`doc/06-deployment-topology.md`](doc/06-deployment-topology.md)\nfor the consumer cookbook.\n\n## Repository layout\n\n```\nsaas-foundation/\n├── packages/\n│   ├── foundation/          # @de-otio/saas-foundation\n│   ├── vestibulum/          # @de-otio/vestibulum\n│   ├── foundation-cdk/      # @de-otio/saas-foundation-cdk\n│   └── vestibulum-cdk/      # @de-otio/vestibulum-cdk\n├── examples/                # consumer integration examples\n├── scripts/                 # cross-package tooling (CI gates, topo build)\n├── doc/                     # design notes — see below\n├── .changeset/              # changesets config\n└── .github/workflows/       # CI + changesets release (version PR + OIDC publish)\n```\n\nThe monorepo layout is specified in\n[`doc/02-monorepo-layout.md`](doc/02-monorepo-layout.md).\n\n## Design documents\n\nThe whole design is in [`doc/`](doc/). Top-level numbered notes\ncover cross-cutting concerns; per-package sub-directories hold the\nmodule-level designs.\n\n**Start here:** [`doc/README.md`](doc/README.md) — index and\nframing.\n\nCross-cutting:\n\n- [`doc/01-scope-and-philosophy.md`](doc/01-scope-and-philosophy.md)\n  — what's in, what's out, OSS-reuse principles, design axioms.\n- [`doc/02-monorepo-layout.md`](doc/02-monorepo-layout.md) —\n  workspaces, tsconfig, ESLint, build orchestration, test framework.\n- [`doc/03-package-relationships.md`](doc/03-package-relationships.md)\n  — dependency arrows, layering rule, bundling story.\n- [`doc/04-shared-vocabulary.md`](doc/04-shared-vocabulary.md) —\n  the frozen cross-package type set (`TenantId`, `AuditEvent`,\n  `RequestContext`, `SecretRef`, claim-resolver callbacks).\n- [`doc/05-versioning-and-releases.md`](doc/05-versioning-and-releases.md)\n  — independent per-package versioning via changesets, semver\n  policy, RFC process for frozen-set changes.\n- [`doc/06-deployment-topology.md`](doc/06-deployment-topology.md)\n  — consumer cookbook for the three deployment archetypes.\n- [`doc/07-vestibulum-migration.md`](doc/07-vestibulum-migration.md)\n  — folding the standalone `vestibulum` repo into this monorepo.\n- [`doc/08-trellis-migration.md`](doc/08-trellis-migration.md) —\n  extracting trellis's generic infrastructure into foundation.\n- [`doc/09-foundation-cdk-package.md`](doc/09-foundation-cdk-package.md)\n  — position doc for the fourth package: scope, dependency arrows,\n  what's in v0.1, what's deferred.\n- [`doc/10-ai-maintained-conventions.md`](doc/10-ai-maintained-conventions.md)\n  — architectural conventions specific to AI-built/maintained code.\n  Operational rules live in [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\nPer-package:\n\n- [`doc/foundation/`](doc/foundation/) — 11 module designs.\n- [`doc/vestibulum/`](doc/vestibulum/) — 8 module designs, plus the\n  [`shared-distribution/`](doc/vestibulum/shared-distribution/)\n  sub-design (shared CloudFront + shared Cognito pool, 10 docs).\n- [`doc/foundation-cdk/`](doc/foundation-cdk/) — 6 construct designs.\n- [`doc/vestibulum-cdk/`](doc/vestibulum-cdk/) — 10 construct and\n  pipeline designs.\n\n## Versioning\n\nIndependent per-package semver via\n[changesets](https://github.com/changesets/changesets). Pre-1.0\nconvention: `0.MINOR.PATCH` where MINOR may be breaking. Frozen-set\ntype changes require an RFC and a coordinated MINOR bump across\nevery affected package; the CI fanout gate enforces this.\n\nDetail: [`doc/05-versioning-and-releases.md`](doc/05-versioning-and-releases.md).\n\n## License\n\nApache-2.0 (matching the standalone `vestibulum` repo this monorepo\nabsorbs); see [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fde-otio%2Fsaas-foundation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fde-otio%2Fsaas-foundation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fde-otio%2Fsaas-foundation/lists"}