mix attesto_phoenix.install (AttestoPhoenix v3.0.0)

Copy Markdown View Source

Installs the attesto_phoenix authorization-server layer into a Phoenix app

Wires the OAuth 2.0 / OpenID Connect authorization-server layer this library provides into the host Phoenix application:

  • adds an AttestoPhoenix.Config config skeleton (issuer, audience, keystore, repo, principal kinds, the Ecto-backed token stores, a chosen :oauth_path_prefix, optional :schema_prefix, and neutral defaults) to the host config, and points the library's global resolver and stores at that OTP app/repo,
  • adds runtime refresh-successor encryption configuration: production reads ATTESTO_REFRESH_SUCCESSOR_SECRET; the bundled Ecto store fails config validation when positive retry grace needs it but custom stores and strict zero-grace deployments do not; development and test use a per-project fallback generated when this task runs,
  • supervises AttestoPhoenix.Store.Sweeper after the host repo so expired Ecto rows are reclaimed and refresh-successor ciphertext is redacted promptly after its short retry window,
  • mounts the server routes (attesto_routes/1) at the chosen prefix into the host router behind a generated config-loading pipeline,
  • scaffolds host callback modules implementing the recommended production behaviours (AttestoPhoenix.ClientStore, PrincipalStore, ScopePolicy, ConsentPolicy, RegistrationStore, EventSink) with documented stub callbacks the host fills in,
  • points the host at mix attesto_phoenix.gen.migration for the Ecto tables the bundled stores read, including the durable refresh-family revocation tombstones. Existing installations upgrading to a release that adds this table must apply its forward migration before boot.

Every step is idempotent: re-running the task does not duplicate the config, the route, or the scaffolded modules. The task never decides authorization policy; it scaffolds the contract the host owns (RFC 6749 §2/§3.3/§4.1.1, RFC 7591 §3, OpenID Connect Core §3.1.2/§5.3) and emits notices telling the host exactly what to fill in.

Example

mix attesto_phoenix.install

Options

  • --oauth-path-prefix - the full client-visible mount prefix for the bundled OAuth endpoints (RFC 8414 §3 advertises the absolute URLs). It must be /oauth or end in /oauth, because the bundled router has fixed /oauth/* endpoint tails; for example, --oauth-path-prefix /mcp/oauth generates attesto_routes(prefix: "/mcp") and advertises /mcp/oauth/*. Unsupported values such as /auth are rejected before any files are changed. If a host needs a different endpoint suffix or an explicit per-endpoint route override, wire the routes manually and set matching advertised paths instead of relying on the generated mount. The well-known documents (RFC 8615) and the JWKS document stay anchored at the host root and are NOT relocated by this prefix.
  • --schema-prefix - the PostgreSQL schema selected by Ecto's prefix: option for every generated table and index. The migration generator uses the same value. The legacy 2.x --table-prefix option is rejected because it controlled literal names in generated migrations, not one coherent runtime layout: most stores queried canonical public tables, while only the CIBA store and sweeper treated it as an Ecto schema prefix.
  • --callbacks-module - the base module the scaffolded callback modules are generated under. Defaults to <App>.AuthZ, yielding <App>.AuthZ.ClientStore and friends.